Azure Storage Blob-clientbibliotheek voor JavaScript - versie 12.26.0

Artikel
11/20/2024

Azure Storage Blob is de oplossing voor objectopslag van Microsoft voor de cloud. Blob Storage is geoptimaliseerd voor het opslaan van enorme hoeveelheden ongestructureerde gegevens. Ongestructureerde gegevens zijn gegevens die niet voldoen aan een bepaald gegevensmodel of bepaalde definitie, zoals tekst of binaire gegevens.

Dit project biedt een clientbibliotheek in JavaScript waarmee u eenvoudig Microsoft Azure Storage Blob-service kunt gebruiken.

Gebruik de clientbibliotheken in dit pakket om:

Eigenschappen van blobservice ophalen/instellen
Containers maken/weergeven/verwijderen
Blok-blobs maken/lezen/weergeven/bijwerken/verwijderen
Pagina-blobs maken/lezen/weergeven/bijwerken/verwijderen
Toevoeg-blobs maken/lezen/weergeven/bijwerken/verwijderen

Sleutelkoppelingen

Slag

Momenteel ondersteunde omgevingen

LTS-versies van Node.js
Nieuwste versies van Safari, Chrome, Edge en Firefox.

Zie ons ondersteuningsbeleid voor meer informatie.

Voorwaarden

Een Azure-abonnement
Een -opslagaccount

Het pakket installeren

De voorkeursmethode voor het installeren van de Azure Storage Blob-clientbibliotheek voor JavaScript is het gebruik van npm-pakketbeheer. Typ het volgende in een terminalvenster:

npm install @azure/storage-blob

De client verifiëren

Azure Storage ondersteunt verschillende manieren om te verifiëren. Als u wilt communiceren met de Azure Blob Storage-service, moet u bijvoorbeeld een exemplaar van een Storage-client maken: BlobServiceClient, ContainerClientof BlobClient. Zie voorbeelden voor het maken van de BlobServiceClient voor meer informatie over verificatie.

Azure Active Directory
gedeelde sleutel
handtekeningen voor gedeelde toegang

Azure Active Directory

De Azure Blob Storage-service ondersteunt het gebruik van Azure Active Directory voor het verifiëren van aanvragen bij de API's. Het @azure/identity-pakket biedt verschillende referentietypen die uw toepassing hiervoor kan gebruiken. Raadpleeg de LEESMIJ voor @azure/identity voor meer informatie en voorbeelden om u op weg te helpen.

Compatibiliteit

Deze bibliotheek is compatibel met Node.js en browsers en gevalideerd op basis van LTS-Node.js versies (>=8.16.0) en de nieuwste versies van Chrome, Firefox en Edge.

Webmedewerkers

Voor deze bibliotheek moeten bepaalde DOM-objecten wereldwijd beschikbaar zijn wanneer ze worden gebruikt in de browser, die webmedewerkers niet standaard beschikbaar maken. U moet deze invullen om deze bibliotheek in webwerkrollen te laten werken.

Raadpleeg onze documentatie voor het gebruik van Azure SDK voor JS in Web Workers voor meer informatie

Deze bibliotheek is afhankelijk van de volgende DOM-API's waarvoor externe polyfills moeten worden geladen wanneer ze worden gebruikt in webwerkrollen:

Verschillen tussen Node.js en browsers

Er zijn verschillen tussen Node.js en runtime van browsers. Wanneer u aan de slag gaat met deze bibliotheek, moet u letten op API's of klassen die zijn gemarkeerd met 'ONLY AVAILABLE IN NODE.JS RUNTIME' of 'ONLY AVAILABLE IN BROWSERS'.

Als een blob gecomprimeerde gegevens in gzip of deflate-indeling bevat en de inhoudscodering dienovereenkomstig is ingesteld, is het downloaden van gedrag anders tussen Node.js en browsers. In Node.js-opslagclients wordt de blob gedownload in de gecomprimeerde indeling, terwijl in browsers de gegevens worden gedownload in de niet-gecomprimeerde indeling.

Functies, interfaces, klassen of functies die alleen beschikbaar zijn in Node.js

Autorisatie van gedeelde sleutels op basis van accountnaam en accountsleutel
- StorageSharedKeyCredential
Sas-generatie (Shared Access Signature)
- generateAccountSASQueryParameters()
- generateBlobSASQueryParameters()
Parallel uploaden en downloaden. Houd er rekening mee dat BlockBlobClient.uploadData() beschikbaar is in zowel Node.js als browsers.
- BlockBlobClient.uploadFile()
- BlockBlobClient.uploadStream()
- BlobClient.downloadToBuffer()
- BlobClient.downloadToFile()

Functies, interfaces, klassen of functies die alleen beschikbaar zijn in browsers

Parallel uploaden en downloaden
- BlockBlobClient.uploadBrowserData()

JavaScript-bundel

Als u deze clientbibliotheek in de browser wilt gebruiken, moet u eerst een bundelaar gebruiken. Raadpleeg onze bundeldocumentatievoor meer informatie over hoe u dit doet.

CORS

U moet CORS-regels (Cross-Origin Resource Sharing) instellen regels voor uw opslagaccount als u voor browsers moet ontwikkelen. Ga naar Azure Portal en Azure Storage Explorer, zoek uw opslagaccount, maak nieuwe CORS-regels voor blob/queue/file/table-service(s).

U kunt bijvoorbeeld de volgende CORS-instellingen maken voor foutopsporing. Maar pas de instellingen zorgvuldig aan op basis van uw vereisten in de productieomgeving.

Toegestane oorsprongen: *
Toegestane werkwoorden: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
Toegestane headers: *
Weergegeven headers: *
Maximale leeftijd (seconden): 86400

Sleutelbegrippen

Blob Storage is ontworpen voor:

Afbeeldingen of documenten rechtstreeks aan een browser leveren.
Bestanden opslaan voor gedistribueerde toegang.
Video en audio streamen.
Schrijven naar logboekbestanden.
Gegevens opslaan voor back-up en herstel, herstel na noodgevallen en archivering.
Gegevens opslaan voor analyse door een on-premises of door Azure gehoste service.

Blob Storage biedt drie typen resources:

Het -opslagaccount dat via BlobServiceClient wordt gebruikt
Een container in het opslagaccount dat via ContainerClient wordt gebruikt
Een blob- in een container die wordt gebruikt via BlobClient

Voorbeelden

het pakket importeren
de blobserviceclient maken
Een nieuwe container maken
de containers weergeven
Een blob maken door gegevens te uploaden
blobs in een container weergeven
Een blob downloaden en deze converteren naar een tekenreeks (Node.js)
een blob downloaden en deze converteren naar een tekenreeks (browsers)

Het pakket importeren

Als u de clients wilt gebruiken, importeert u het pakket in uw bestand:

const AzureStorageBlob = require("@azure/storage-blob");

U kunt ook selectief alleen de typen importeren die u nodig hebt:

const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");

De blobserviceclient maken

De BlobServiceClient vereist een URL naar de blobservice en een toegangsreferentie. Het accepteert desgewenst ook bepaalde instellingen in de parameter options.

met `DefaultAzureCredential` uit `@azure/identity` pakket

Aanbevolen manier om een BlobServiceClient te instantiëren

Installatie : Naslaginformatie - Toegang tot blobs en wachtrijen autoriseren met Azure Active Directory vanuit een clienttoepassing - /azure/storage/common/storage-auth-aad-app

Een nieuwe AAD-toepassing registreren en machtigingen verlenen voor toegang tot Azure Storage namens de aangemelde gebruiker
- Een nieuwe toepassing registreren in Azure Active Directory (in azure-portal) - /azure/active-directory/develop/quickstart-register-app
- Selecteer Add a permission in de sectie API permissions en kies Microsoft APIs.
- Kies Azure Storage en schakel het selectievakje naast user_impersonation in en klik vervolgens op Add permissions. Hierdoor heeft de toepassing namens de aangemelde gebruiker toegang tot Azure Storage.
Toegang verlenen tot Azure Blob-gegevens met RBAC in azure Portal
- RBAC-rollen voor blobs en wachtrijen : /azure/storage/common/storage-auth-aad-rbac-portal.
- Ga in azure Portal naar uw opslagaccount en wijs rol Inzender voor opslagblobgegevens toe aan de geregistreerde AAD-toepassing vanaf Access control (IAM) tabblad (in de navigatiebalk aan de linkerkant van uw opslagaccount in azure-portal).
Omgeving instellen voor het voorbeeld
- Noteer op de overzichtspagina van uw AAD-toepassing de CLIENT ID en TENANT ID. Maak op het tabblad Certificaten & Geheimen een geheim en noteer dat.
- Zorg ervoor dat u AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET als omgevingsvariabelen om het voorbeeld uit te voeren (kan gebruikmaken van process.env).

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

// Enter your storage account name
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

Zie het Azure AD-verificatievoorbeeld voor een volledig voorbeeld met behulp van deze methode.

[Opmerking: bovenstaande stappen zijn alleen bedoeld voor Node.js]

verbindingsreeks gebruiken

U kunt ook een BlobServiceClient maken met behulp van de statische methode fromConnectionString() met de volledige verbindingsreeks als argument. (De verbindingsreeks kan worden verkregen via azure Portal.) [ALLEEN BESCHIKBAAR IN NODE.JS RUNTIME]

const { BlobServiceClient } = require("@azure/storage-blob");

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

met `StorageSharedKeyCredential`

U kunt ook een BlobServiceClient maken met een StorageSharedKeyCredential door accountnaam en accountsleutel door te geven als argumenten. (De accountnaam en accountsleutel kunnen worden verkregen via de Azure-portal.) [ALLEEN BESCHIKBAAR IN NODE.JS RUNTIME]

const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");

// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";

// Use StorageSharedKeyCredential with storage account and account key
// StorageSharedKeyCredential is only available in Node.js runtime, not in browsers
const sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  sharedKeyCredential
);

met SAS-token

U kunt ook een BlobServiceClient maken met shared access signatures (SAS). U kunt het SAS-token ophalen uit azure Portal of er een genereren met behulp van generateAccountSASQueryParameters().

const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";

const blobServiceClient = new BlobServiceClient(`https://${account}.blob.core.windows.net${sas}`);

Een nieuwe container maken

Gebruik BlobServiceClient.getContainerClient() om een containerclientinstantie op te halen en vervolgens een nieuwe containerresource te maken.

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  // Create a container
  const containerName = `newcontainer${new Date().getTime()}`;
  const containerClient = blobServiceClient.getContainerClient(containerName);
  const createContainerResponse = await containerClient.create();
  console.log(`Create container ${containerName} successfully`, createContainerResponse.requestId);
}

main();

De containers weergeven

Gebruik BlobServiceClient.listContainers() functie om de containers te herhalen, met de nieuwe for-await-of syntaxis:

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  const containers = blobServiceClient.listContainers();
  for await (const container of containers) {
    console.log(`Container ${i++}: ${container.name}`);
  }
}

main();

U kunt ook for-await-of:

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  const iter = blobServiceClient.listContainers();
  let containerItem = await iter.next();
  while (!containerItem.done) {
    console.log(`Container ${i++}: ${containerItem.value.name}`);
    containerItem = await iter.next();
  }
}

main();

Daarnaast wordt paginering ook ondersteund voor vermelding via byPage():

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  for await (const response of blobServiceClient.listContainers().byPage({ maxPageSize: 20 })) {
    if (response.containerItems) {
      for (const container of response.containerItems) {
        console.log(`Container ${i++}: ${container.name}`);
      }
    }
  }
}

main();

Zie samples/v12/typescript/src/listContainers.tsvoor een volledig voorbeeld van het herhalen van containers.

Een blob maken door gegevens te uploaden

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

const containerName = "<container name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);

  const content = "Hello world!";
  const blobName = "newblob" + new Date().getTime();
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);
  const uploadBlobResponse = await blockBlobClient.upload(content, content.length);
  console.log(`Upload block blob ${blobName} successfully`, uploadBlobResponse.requestId);
}

main();

Blobs in een container weergeven

Vergelijkbaar met het weergeven van containers.

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

const containerName = "<container name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);

  let i = 1;
  const blobs = containerClient.listBlobsFlat();
  for await (const blob of blobs) {
    console.log(`Blob ${i++}: ${blob.name}`);
  }
}

main();

Zie samples/v12/typescript/src/listBlobsFlat.tsvoor een volledig voorbeeld van het herhalen van blobs.

Een blob downloaden en converteren naar een tekenreeks (Node.js)

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

const containerName = "<container name>";
const blobName = "<blob name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);
  const blobClient = containerClient.getBlobClient(blobName);

  // Get blob content from position 0 to the end
  // In Node.js, get downloaded data by accessing downloadBlockBlobResponse.readableStreamBody
  const downloadBlockBlobResponse = await blobClient.download();
  const downloaded = (
    await streamToBuffer(downloadBlockBlobResponse.readableStreamBody)
  ).toString();
  console.log("Downloaded blob content:", downloaded);

  // [Node.js only] A helper method used to read a Node.js readable stream into a Buffer
  async function streamToBuffer(readableStream) {
    return new Promise((resolve, reject) => {
      const chunks = [];
      readableStream.on("data", (data) => {
        chunks.push(data instanceof Buffer ? data : Buffer.from(data));
      });
      readableStream.on("end", () => {
        resolve(Buffer.concat(chunks));
      });
      readableStream.on("error", reject);
    });
  }
}

main();

Download een blob en converteer deze naar een tekenreeks (browsers).

Raadpleeg de sectie JavaScript Bundle voor meer informatie over het gebruik van deze bibliotheek in de browser.

const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const containerName = "<container name>";
const blobName = "<blob name>";

const blobServiceClient = new BlobServiceClient(`https://${account}.blob.core.windows.net${sas}`);

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);
  const blobClient = containerClient.getBlobClient(blobName);

  // Get blob content from position 0 to the end
  // In browsers, get downloaded data by accessing downloadBlockBlobResponse.blobBody
  const downloadBlockBlobResponse = await blobClient.download();
  const downloaded = await blobToString(await downloadBlockBlobResponse.blobBody);
  console.log("Downloaded blob content", downloaded);

  // [Browsers only] A helper method used to convert a browser Blob into string.
  async function blobToString(blob) {
    const fileReader = new FileReader();
    return new Promise((resolve, reject) => {
      fileReader.onloadend = (ev) => {
        resolve(ev.target.result);
      };
      fileReader.onerror = reject;
      fileReader.readAsText(blob);
    });
  }
}

main();

Een volledig voorbeeld van eenvoudige scenario's is op samples/v12/typescript/src/sharedKeyAuth.ts.

Probleemoplossing

Het inschakelen van logboekregistratie kan helpen nuttige informatie over fouten te ontdekken. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de omgevingsvariabele AZURE_LOG_LEVEL in op info. U kunt logboekregistratie ook tijdens runtime inschakelen door setLogLevel aan te roepen in de @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Volgende stappen

Meer codevoorbeelden:

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.

Raadpleeg ook storage-specifieke handleiding voor aanvullende informatie over het instellen van de testomgeving voor opslagbibliotheken.

indrukken

Delen via

Azure Storage Blob-clientbibliotheek voor JavaScript - versie 12.26.0

Slag

Momenteel ondersteunde omgevingen

Voorwaarden

Het pakket installeren

De client verifiëren

Azure Active Directory

Compatibiliteit

Webmedewerkers

Verschillen tussen Node.js en browsers

Functies, interfaces, klassen of functies die alleen beschikbaar zijn in Node.js

Functies, interfaces, klassen of functies die alleen beschikbaar zijn in browsers

JavaScript-bundel

CORS

Sleutelbegrippen

Voorbeelden

Het pakket importeren

De blobserviceclient maken

met `DefaultAzureCredential` uit `@azure/identity` pakket

verbindingsreeks gebruiken

met `StorageSharedKeyCredential`

met SAS-token

Een nieuwe container maken

De containers weergeven

Een blob maken door gegevens te uploaden

Blobs in een container weergeven

Een blob downloaden en converteren naar een tekenreeks (Node.js)

Download een blob en converteer deze naar een tekenreeks (browsers).

Probleemoplossing

Volgende stappen

Bijdragen

Aanvullende resources

Delen via

Azure Storage Blob-clientbibliotheek voor JavaScript - versie 12.26.0

Slag

Momenteel ondersteunde omgevingen

Voorwaarden

Het pakket installeren

De client verifiëren

Azure Active Directory

Compatibiliteit

Webmedewerkers

Verschillen tussen Node.js en browsers

Functies, interfaces, klassen of functies die alleen beschikbaar zijn in Node.js

Functies, interfaces, klassen of functies die alleen beschikbaar zijn in browsers

JavaScript-bundel

CORS

Sleutelbegrippen

Voorbeelden

Het pakket importeren

De blobserviceclient maken

met DefaultAzureCredential uit @azure/identity pakket

verbindingsreeks gebruiken

met StorageSharedKeyCredential

met SAS-token

Een nieuwe container maken

De containers weergeven

Een blob maken door gegevens te uploaden

Blobs in een container weergeven

Een blob downloaden en converteren naar een tekenreeks (Node.js)

Download een blob en converteer deze naar een tekenreeks (browsers).

Probleemoplossing

Volgende stappen

Bijdragen

Aanvullende resources

met `DefaultAzureCredential` uit `@azure/identity` pakket

met `StorageSharedKeyCredential`