Delen via

Azure Storage Blob-clientbibliotheek voor JavaScript - versie 12.29.1

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

Belangrijke links

Aan de slag

Momenteel ondersteunde omgevingen

Zie ons ondersteuningsbeleid voor meer informatie.

Prerequisites

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

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.

Compatibility

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 Werkers

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

Belangrijke concepten

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 wordt gebruikt via BlobServiceClient
  • Een container in de opslagaccount die wordt gebruikt via ContainerClient
  • Een blob in een container die wordt gebruikt via BlobClient

Examples

Het pakket importeren

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

import * as AzureStorageBlob from "@azure/storage-blob";

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

import { BlobServiceClient, StorageSharedKeyCredential } from "@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

Instelling : Naslaginformatie - Toegang tot blobs en wachtrijen autoriseren met Azure Active Directory vanuit een clienttoepassing - https://free.blessedness.top/azure/storage/common/storage-auth-aad-app

  • Een nieuwe AAD-toepassing registreren en machtigingen verlenen voor toegang tot Azure Storage namens de aangemelde gebruiker

    • Registreer een nieuwe applicatie in de Azure Active Directory (in de azure-portal) - https://free.blessedness.top/azure/active-directory/develop/quickstart-register-app
    • Selecteer API permissions in de sectie Add a permission 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

  • 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).
import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@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]

import { BlobServiceClient } from "@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]

import { StorageSharedKeyCredential, BlobServiceClient } from "@azure/storage-blob";

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

import { BlobServiceClient } from "@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.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

// 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);

De containers weergeven

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

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

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

U kunt ook for-await-of:

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

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

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

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

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

Voor een volledig voorbeeld van itererende containers, zie samples/v12/typescript/src/listContainers.ts.

Een blob maken door gegevens te uploaden

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

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

Blobs in een container weergeven

Vergelijkbaar met het weergeven van containers.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

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

Voor een volledig voorbeeld van itererende blobs zie samples/v12/typescript/src/listBlobsFlat.ts.

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

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

const containerName = "<container name>";
const blobName = "<blob name>";
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();
if (downloadBlockBlobResponse.readableStreamBody) {
  const downloaded = await streamToString(downloadBlockBlobResponse.readableStreamBody);
  console.log(`Downloaded blob content: ${downloaded}`);
}

async function streamToString(stream: NodeJS.ReadableStream): Promise<string> {
  const result = await new Promise<Buffer<ArrayBuffer>>((resolve, reject) => {
    const chunks: Buffer[] = [];
    stream.on("data", (data) => {
      chunks.push(Buffer.isBuffer(data) ? data : Buffer.from(data));
    });
    stream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    stream.on("error", reject);
  });
  return result.toString();
}

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.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

const containerName = "<container name>";
const blobName = "<blob name>";
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 blobBody = await downloadBlockBlobResponse.blobBody;
if (blobBody) {
  const downloaded = await blobBody.text();
  console.log(`Downloaded blob content: ${downloaded}`);
}

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

Troubleshooting

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:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Volgende stappen

Meer codevoorbeelden:

Contributing

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.