Azure Storage Blob-clientbibliotheek voor JavaScript - versie 12.17.0

Artikel
11/10/2023

Azure Storage Blob is de oplossing voor objectopslag van Microsoft voor de cloud. Blob Storage is geoptimaliseerd voor het opslaan van enorme hoeveelheden niet-structureerde 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 voor het volgende:

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

Belangrijke koppelingen

Aan de slag

Momenteel ondersteunde omgevingen

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

Zie ons ondersteuningsbeleid voor meer informatie.

Vereisten

Een Azure-abonnement
Een opslagaccount

Het pakket installeren

De beste manier om de Azure Storage Blob-clientbibliotheek voor JavaScript te installeren, is met behulp 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 een exemplaar van een Storage-client maken, BlobServiceClientbijvoorbeeld , ContainerClientofBlobClient. 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 om aanvragen voor de API's te verifiëren. Het @azure/identity pakket biedt verschillende referentietypen die uw toepassing kan gebruiken om dit te doen. Raadpleeg leesmij voor @azure/identity voor meer informatie en voorbeelden om aan de slag te gaan.

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.

Web Workers

Deze bibliotheek vereist dat bepaalde DOM-objecten globaal beschikbaar zijn wanneer ze worden gebruikt in de browser. Deze webwerkrollen maken deze niet standaard beschikbaar. U moet deze invullen om deze bibliotheek te laten werken in webwerkrollen.

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 deze worden gebruikt in webwerkrollen:

Verschillen tussen Node.js en browsers

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

Als een blob gecomprimeerde gegevens in of-indeling gzipdeflate bevat en de inhoudscodering dienovereenkomstig is ingesteld, verschilt het downloadgedrag tussen Node.js en browsers. In Node.js opslagclients de blob downloaden in de gecomprimeerde indeling, terwijl in browsers de gegevens worden gedownload in een 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 bundler gebruiken. Raadpleeg onze bundeldocumentatie voor meer informatie over hoe u dit doet.

CORS

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

U kunt bijvoorbeeld de volgende CORS-instellingen maken voor foutopsporing. Pas de instellingen echter 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

Belangrijkste concepten

BLOB Storage is ontworpen voor:

Het rechtstreeks aan een browser leveren van afbeeldingen of documenten.
De opslag van bestanden voor gedistribueerde toegang.
Streaming van video en audio.
Schrijven naar logboekbestanden.
De opslag van gegevens voor back-up en herstel, herstel na noodgevallen en archivering.
De opslag van gegevens voor analyse door een on-premises of in Azure gehoste service.

Er zijn drie typen resources voor blobopslag:

Het opslagaccount dat wordt gebruikt via BlobServiceClient
Een container in het opslagaccount dat wordt gebruikt via ContainerClient
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 converteren naar een tekenreeks (Node.js)
Een blob downloaden en 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 optioneel ook enkele instellingen in de options parameter.

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

Aanbevolen manier om een instantiëring te maken BlobServiceClient

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

Een nieuwe AAD-toepassing registreren en namens de aangemelde gebruiker machtigingen verlenen voor toegang tot Azure Storage
- Een nieuwe toepassing registreren in Azure Active Directory (in de azure-portal) - /azure/active-directory/develop/quickstart-register-app
- Selecteer Add a permission en kies Microsoft APIsin de API permissions sectie .
- Selecteer Azure Storage het selectievakje naast user_impersonation en klik op Add permissions. Hierdoor heeft de toepassing toegang tot Azure Storage namens de aangemelde gebruiker.
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 de rol Inzender voor opslagblobgegevens toe aan de geregistreerde AAD-toepassing vanaf Access control (IAM) het tabblad (in de linkernavigatiebalk van uw opslagaccount in azure-portal).
Omgevingsinstellingen 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 hebt om het voorbeeld met succes 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 voorbeeld Azure AD Auth voor een volledig voorbeeld met behulp van deze methode.

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

met behulp van verbindingsreeks

U kunt ook een BlobServiceClient instantiëren met behulp van de fromConnectionString() statische methode met de volledige verbindingsreeks als argument. (De verbindingsreeks kunt u verkrijgen 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 instantiëren met een StorageSharedKeyCredential door accountnaam en accountsleutel door te geven als argumenten. (De accountnaam en de 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 instantiëren met een SAS (Shared Access Signatures). U kunt het SAS-token ophalen uit de Azure-portal of een token 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 maak vervolgens een nieuwe containerresource.

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() de 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;
  let containers = blobServiceClient.listContainers();
  for await (const container of containers) {
    console.log(`Container ${i++}: ${container.name}`);
  }
}

main();

U kunt ook het volgende doen for-await-ofzonder :

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;
  let 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.ts voor een volledig voorbeeld van iteratiecontainers.

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;
  let blobs = containerClient.listBlobsFlat();
  for await (const blob of blobs) {
    console.log(`Blob ${i++}: ${blob.name}`);
  }
}

main();

Zie samples/v12/typescript/src/listBlobsFlat.ts voor 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-bundel 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 vindt u in samples/v12/typescript/src/sharedKeyAuth.ts.

Problemen oplossen

Het inschakelen van logboekregistratie kan helpen bij het ontdekken van nuttige informatie over fouten. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de AZURE_LOG_LEVEL omgevingsvariabele in op info. Logboekregistratie kan ook worden ingeschakeld tijdens runtime door aan te roepen setLogLevel 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 handleiding voor bijdragen voor meer informatie over het bouwen en testen van de code.

Raadpleeg ook De specifieke handleiding voor opslag voor meer informatie over het instellen van de testomgeving voor opslagbibliotheken.

Weergaven

Azure Storage Blob-clientbibliotheek voor JavaScript - versie 12.17.0

Aan de slag

Momenteel ondersteunde omgevingen

Vereisten

Het pakket installeren

De client verifiëren

Azure Active Directory

Compatibiliteit

Web Workers

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

Belangrijkste concepten

Voorbeelden

Het pakket importeren

De blobserviceclient maken

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

met behulp van verbindingsreeks

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).

Problemen oplossen

Volgende stappen

Bijdragen

Feedback

Aanvullende resources

Azure Storage Blob-clientbibliotheek voor JavaScript - versie 12.17.0

Aan de slag

Momenteel ondersteunde omgevingen

Vereisten

Het pakket installeren

De client verifiëren

Azure Active Directory

Compatibiliteit

Web Workers

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

Belangrijkste concepten

Voorbeelden

Het pakket importeren

De blobserviceclient maken

met DefaultAzureCredential van @azure/identity pakket

met behulp van verbindingsreeks

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).

Problemen oplossen

Volgende stappen

Bijdragen

Feedback

Aanvullende resources

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

Met `StorageSharedKeyCredential`