Freigeben über

Azure Storage-Blobclientbibliothek für JavaScript – Version 12.29.1

Azure Storage Blob ist die Objektspeicherlösung von Microsoft für die Cloud. Blob-Speicher ist für die Speicherung massiver Mengen unstrukturierter Daten optimiert. Unstrukturierte Daten sind Daten, die keinem bestimmten Datenmodell oder einer bestimmten Definition entsprechen, z. B. Text oder Binärdaten.

Dieses Projekt stellt eine Clientbibliothek in JavaScript bereit, die die Nutzung des Microsoft Azure Storage Blob-Diensts erleichtert.

Verwenden Sie die Clientbibliotheken in diesem Paket, um:

  • Abrufen/Festlegen von Blob-Diensteigenschaften
  • Container erstellen/auflisten/löschen
  • Erstellen/Lesen/Auflisten/Aktualisieren/Löschen von Blockblobs
  • Erstellen/Lesen/Liste/Aktualisieren/Löschen von Seitenblobs
  • Erstellen/Lesen/Auflisten/Aktualisieren/Löschen von Anfügeblobs

Wichtige Links

Erste Schritte

Derzeit unterstützte Umgebungen

Weitere Informationen finden Sie in unserer Supportrichtlinie.

Prerequisites

Installieren des Pakets

Die bevorzugte Methode zum Installieren der Azure Storage Blob-Clientbibliothek für JavaScript ist die Verwendung des npm-Paket-Managers. Geben Sie Folgendes in ein Terminalfenster ein:

npm install @azure/storage-blob

Authentifizieren des Clients

Azure Storage unterstützt mehrere Möglichkeiten zur Authentifizierung. Um mit dem Azure Blob Storage-Dienst zu interagieren, müssen Sie beispielsweise eine Instanz eines Speicherclients erstellen – BlobServiceClient, ContainerClientoder BlobClient. Weitere Informationen zur Authentifizierung finden Sie in Beispielen zum Erstellen des BlobServiceClient.

Azure Active Directory

Der Azure Blob Storage-Dienst unterstützt die Verwendung von Azure Active Directory zum Authentifizieren von Anforderungen an seine APIs. Das @azure/identity-Paket bietet eine Vielzahl von Anmeldeinformationstypen, die Ihre Anwendung verwenden kann, um dies zu tun. Weitere Details und Beispiele für die ersten Schritte finden Sie in der README für @azure/identity.

Compatibility

Diese Bibliothek ist mit Node.js und Browsern kompatibel und wird mit LTS-Node.js-Versionen (>=8.16.0) und den neuesten Versionen von Chrome, Firefox und Edge überprüft.

Web-Arbeiter

Diese Bibliothek erfordert, dass bestimmte DOM-Objekte global verfügbar sind, wenn sie im Browser verwendet werden, die Web-Worker standardmäßig nicht verfügbar machen. Sie müssen diese polyausfüllen, damit diese Bibliothek in Web-Workern funktioniert.

Weitere Informationen finden Sie in unserer Dokumentation zur Verwendung des Azure SDK für JS in Web Workers

Diese Bibliothek hängt von den folgenden DOM-APIs ab, die externe Polyfills benötigen, die bei Verwendung in Web-Workern geladen werden:

Unterschiede zwischen Node.js und Browsern

Es gibt Unterschiede zwischen Node.js und Browserlaufzeit. Achten Sie bei den ersten Schritten mit dieser Bibliothek auf APIs oder Klassen, die mit "NUR IN NODE.JS RUNTIME VERFÜGBAR" gekennzeichnet sind, oder "NUR IN BROWSERN VERFÜGBAR".

  • Wenn ein Blob komprimierte Daten im gzip- oder deflate Format enthält und die Codierung entsprechend festgelegt ist, unterscheidet sich das Downloadverhalten zwischen Node.js und Browsern. In Node.js Speicherclients laden das BLOB im komprimierten Format herunter, während die Daten in Browsern im komprimierten Format heruntergeladen werden.
Features, Schnittstellen, Klassen oder Funktionen nur in Node.js
  • Gemeinsame Schlüsselautorisierung basierend auf Kontoname und Kontoschlüssel
    • StorageSharedKeyCredential
  • Generierung von Shared Access Signature(SAS)
    • generateAccountSASQueryParameters()
    • generateBlobSASQueryParameters()
  • Paralleles Hochladen und Herunterladen. Beachten Sie, dass BlockBlobClient.uploadData() sowohl in Node.js als auch in Browsern verfügbar ist.
    • BlockBlobClient.uploadFile()
    • BlockBlobClient.uploadStream()
    • BlobClient.downloadToBuffer()
    • BlobClient.downloadToFile()
Features, Schnittstellen, Klassen oder Funktionen, die nur in Browsern verfügbar sind
  • Paralleles Hochladen und Herunterladen
    • BlockBlobClient.uploadBrowserData()

JavaScript-Bündel

Um diese Clientbibliothek im Browser zu verwenden, müssen Sie zuerst einen Bundler verwenden. Ausführliche Informationen dazu finden Sie in unserer Bündelungsdokumentation.

CORS

Sie müssen Cross-Origin Resource Sharing (CORS) Regeln für Ihr Speicherkonto einrichten, wenn Sie für Browser entwickeln müssen. Wechseln Sie zu Azure-Portal und Azure Storage-Explorer, suchen Sie Ihr Speicherkonto, erstellen Sie neue CORS-Regeln für blob/queue/file/table service(s).

Sie können z. B. die folgenden CORS-Einstellungen für das Debuggen erstellen. Passen Sie die Einstellungen jedoch entsprechend Ihren Anforderungen in der Produktionsumgebung sorgfältig an.

  • Zulässige Ursprünge: *
  • Zulässige Verben: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
  • Zulässige Kopfzeilen: *
  • Verfügbar gemachte Kopfzeilen: *
  • Höchstalter (Sekunden): 86400

Wichtige Begriffe

Blob-Speicher wurde für Folgendes entwickelt:

  • Direktes Verarbeiten von Bildern oder Dokumenten an einen Browser.
  • Speichern von Dateien für den verteilten Zugriff.
  • Streamen von Video und Audio.
  • Schreiben in Protokolldateien.
  • Speichern von Daten für Sicherung und Wiederherstellung, Notfallwiederherstellung und Archivierung.
  • Speichern von Daten für die Analyse durch einen lokalen oder von Azure gehosteten Dienst.

Blob-Speicher bietet drei Arten von Ressourcen:

  • Das Speicherkonto , das über BlobServiceClient
  • Ein Container im Speicherkonto, der über ContainerClient
  • Ein Blob in einem Container, der über BlobClient

Examples

Importieren des Pakets

Um die Clients zu verwenden, importieren Sie das Paket in Ihre Datei:

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

Alternativ können Sie nur die benötigten Typen selektiv importieren:

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

Erstellen des BLOB-Dienstclients

Für die BlobServiceClient ist eine URL zum BLOB-Dienst und eine Zugriffsanmeldeinformationen erforderlich. Sie akzeptiert optional auch einige Einstellungen im options-Parameter.

mit DefaultAzureCredential aus @azure/identity Paket

Empfohlene Methode zum Instanziieren eines BlobServiceClient

Setup: Referenz – Autorisieren des Zugriffs auf Blobs und Warteschlangen mit Azure Active Directory über eine Clientanwendung – https://learn.microsoft.com/azure/storage/common/storage-auth-aad-app

  • Registrieren einer neuen AAD-Anwendung und Erteilen von Berechtigungen für den Zugriff auf Azure Storage im Namen des angemeldeten Benutzers

    • Registrieren einer neuen Anwendung im Azure Active Directory (im azure-portal) – https://learn.microsoft.com/azure/active-directory/develop/quickstart-register-app
    • Wählen Sie im Abschnitt API permissionsAdd a permission aus, und wählen Sie Microsoft APIsaus.
    • Wählen Sie Azure Storage aus, und aktivieren Sie das Kontrollkästchen neben user_impersonation, und klicken Sie dann auf Add permissions. Dadurch kann die Anwendung im Namen des angemeldeten Benutzers auf Azure Storage zugreifen.

  • Gewähren des Zugriffs auf Azure Blob-Daten mit RBAC im Azure-Portal

  • Umgebungssetup für das Beispiel

    • Notieren Sie sich auf der Übersichtsseite Ihrer AAD-Anwendung die CLIENT ID und TENANT ID. Erstellen Sie auf der Registerkarte "Zertifikate & Geheime Schlüssel" einen geheimen Schlüssel, und notieren Sie sich dies unten.
    • Stellen Sie sicher, dass Sie AZURE_TENANT_ID, AZURE_CLIENT_ID, als Umgebungsvariablen AZURE_CLIENT_SECRET haben, um das Beispiel erfolgreich auszuführen(Kann process.env nutzen).
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,
);

Ein vollständiges Beispiel mit dieser Methode finden Sie im Azure AD Auth-Beispiel.

[Hinweis - Oben aufgeführte Schritte sind nur für Node.js]

verwenden der Verbindungszeichenfolge

Alternativ können Sie eine BlobServiceClient mithilfe der fromConnectionString() statischen Methode mit der vollständigen Verbindungszeichenfolge als Argument instanziieren. (Die Verbindungszeichenfolge kann aus dem Azure-Portal abgerufen werden.) [NUR IN NODE.JS RUNTIME VERFÜGBAR]

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

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

mit StorageSharedKeyCredential

Alternativ instanziieren Sie eine BlobServiceClient mit einem StorageSharedKeyCredential, indem Sie Kontoname und Kontoschlüssel als Argumente übergeben. (Der Kontoname und der Kontoschlüssel können über das Azure-Portal abgerufen werden.) [NUR IN NODE.JS RUNTIME VERFÜGBAR]

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

mit SAS-Token

Außerdem können Sie eine BlobServiceClient mit einer freigegebenen Zugriffssignatur (SAS) instanziieren. Sie können das SAS-Token aus dem Azure-Portal abrufen oder mithilfe von generateAccountSASQueryParameters()generieren.

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}`);

Erstellen eines neuen Containers

Verwenden Sie BlobServiceClient.getContainerClient(), um eine Containerclientinstanz abzurufen und dann eine neue Containerressource zu erstellen.

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

Auflisten der Container

Verwenden Sie BlobServiceClient.listContainers() Funktion, um die Container mit der neuen for-await-of-Syntax zu durchlaufen:

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}`);
}

Alternativ ohne 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());
}

Darüber hinaus wird Paginierung auch für die Auflistung über byPage()unterstützt:

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}`);
  }
}

Ein vollständiges Beispiel zum Iterieren von Containern finden Sie unter samples/v12/typescript/src/listContainers.ts.

Erstellen eines Blobs durch Hochladen von Daten

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}`,
);

Auflisten von Blobs in einem Container

Ähnlich wie beim Auflisten von Containern.

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}`);
}

Ein vollständiges Beispiel zum Iterieren von Blobs finden Sie unter samples/v12/typescript/src/listBlobsFlat.ts.

Herunterladen eines Blobs und Konvertieren in eine Zeichenfolge (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();
}

Laden Sie ein BLOB herunter, und konvertieren Sie es in eine Zeichenfolge (Browser).

Weitere Informationen zur Verwendung dieser Bibliothek im Browser finden Sie im Abschnitt JavaScript-Paket .

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}`);
}

Ein vollständiges Beispiel für einfache Szenarien finden Sie unter samples/v12/typescript/src/sharedKeyAuth.ts.

Troubleshooting

Das Aktivieren der Protokollierung kann hilfreiche Informationen zu Fehlern aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf infofest. Alternativ kann die Protokollierung zur Laufzeit durch Aufrufen von setLogLevel im @azure/loggeraktiviert werden:

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

setLogLevel("info");

Nächste Schritte

Weitere Codebeispiele:

Contributing

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie bitte den mitwirkenden Leitfaden, um mehr über das Erstellen und Testen des Codes zu erfahren.

Weitere Informationen zum Einrichten der Testumgebung für Speicherbibliotheken finden Sie auch in speicherspezifischen Leitfaden.

  • Last updated on