Azure Storage-Blobclientbibliothek für JavaScript– Version 12.23.0
Azure Storage Blob ist die Objektspeicherlösung von Microsoft für die Cloud. Blob Storage ist für die Speicherung großer Mengen unstrukturierter Daten optimiert. Unstrukturierte Daten sind Daten, die keinem bestimmten Datenmodell und keiner bestimmten Definition entsprechen (also beispielsweise Text- oder Binärdaten).
Dieses Projekt stellt eine Clientbibliothek in JavaScript bereit, die die Nutzung des Microsoft Azure Storage-Blobdiensts erleichtert.
Verwenden Sie die Clientbibliotheken in diesem Paket für Folgendes:
- Abrufen/Festlegen von Blobdiensteigenschaften
- Erstellen/Auflisten/Löschen von Containern
- Erstellen/Lesen/Auflisten/Aktualisieren/Löschen von Blockblobs
- Erstellen/Lesen/Auflisten/Aktualisieren/Löschen von Seitenblobs
- Erstellen/Lesen/Auflisten/Aktualisieren/Löschen von Anfügeblobs
Schlüssellinks
- Quellcode
- Paket (npm)
- API-Referenzdokumentation
- Produktdokumentation
- Beispiele
- Azure Storage-Blob-REST-APIs
Erste Schritte
Die derzeitig unterstützten Umgebungen
- LTS-Versionen von Node.js
- Neueste Versionen von Safari, Chrome, Edge und Firefox.
Ausführlichere Informationen finden Sie in der Supportrichtlinie.
Voraussetzungen
Installieren des Pakets
Die bevorzugte Methode zum Installieren der Azure Storage-Blobclientbibliothek 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 Authentifizierungsmethoden. Um mit dem Azure Blob Storage-Dienst zu interagieren, müssen Sie eine Instanz eines Storage-Clients erstellen, BlobServiceClient
z. B. , ContainerClient
oder BlobClient
. Weitere Informationen zur Authentifizierung finden Sie in den Beispielen zum Erstellen von 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 dazu verwenden kann. Weitere Informationen und Beispiele für @azure/identity
die ersten Schritte finden Sie in der INFODATEI.
Kompatibilität
Diese Bibliothek ist mit Node.js und Browsern kompatibel und mit LTS Node.js Versionen (>=8.16.0) und den neuesten Versionen von Chrome, Firefox und Edge überprüft.
Web Worker
Diese Bibliothek erfordert, dass bestimmte DOM-Objekte global verfügbar sind, wenn sie im Browser verwendet werden, was Webworker 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 Workern.
Diese Bibliothek hängt von den folgenden DOM-APIs ab, die externe Polyfills laden müssen, wenn sie in Web-Workern verwendet 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 "ONLY AVAILABLE IN NODE.JS RUNTIME" oder "ONLY AVAILABLE IN BROWSERS" gekennzeichnet sind.
- Wenn ein Blob komprimierte Daten im Format oder
deflate
imgzip
Format enthält und die Inhaltscodierung entsprechend festgelegt ist, unterscheidet sich das Downloadverhalten zwischen Node.js und Browsern. In Node.js Speicherclients das Blob im komprimierten Format herunterladen, während in Browsern die Daten im dekomprimierten Format heruntergeladen werden.
Features, Schnittstellen, Klassen oder Funktionen, die nur in Node.js
- Autorisierung mit gemeinsam genutzten Schlüsseln 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-Paket
Um diese Clientbibliothek im Browser verwenden zu können, müssen Sie zunächst einen Bundler verwenden. Ausführliche Informationen dazu finden Sie in unserer Bündelungsdokumentation.
CORS
Sie müssen CORS-Regeln (Cross-Origin Resource Sharing) für Ihr Speicherkonto einrichten, wenn Sie für Browser entwickeln müssen. Navigieren Sie zum Azure-Portal und zum Azure Storage-Explorer, suchen Sie Nach Ihrem Speicherkonto, und erstellen Sie neue CORS-Regeln für blob/queue/file/table-Dienste.
Sie können beispielsweise die folgenden CORS-Einstellungen für das Debuggen erstellen. Passen Sie die Einstellungen jedoch sorgfältig an Ihre Anforderungen in der Produktionsumgebung an.
- Zulässige Ursprünge: *
- Zulässige Verben: DELETE, GET, HEAD, MERGE, POST, OPTIONS, PUT
- Zulässige Header: *
- Verfügbar gemachte Header: *
- Maximales Alter (Sekunden): 86400
Wichtige Begriffe
Blobspeicher ist für Folgendes konzipiert:
- Speichern von Bildern oder Dokumenten direkt für einen Browser
- Speichern von Dateien für verteilten Zugriff
- Video- und Audio-Streaming
- Schreiben in Protokolldateien
- Speichern von Daten für Sicherung und Wiederherstellung, Notfallwiederherstellung und Archivierung
- Speichern von Daten für Analysen durch einen lokalen oder von Azure gehosteten Dienst
Blob Storage bietet drei Typen von Ressourcen:
- Das über verwendete Speicherkonto
BlobServiceClient
- Ein Container im Speicherkonto, das über verwendet wird
ContainerClient
- Ein Blob in einem Container, der über verwendet wird
BlobClient
Beispiele
- Importieren des Pakets
- Erstellen des Blob-Dienstclients
- Erstellen eines neuen Containers
- Auflisten der Container
- Erstellen eines Blobs durch Hochladen von Daten
- Auflisten von Blobs in einem Container
- Herunterladen eines Blobs und Konvertieren in eine Zeichenfolge (Node.js)
- Herunterladen eines Blobs und Konvertieren in eine Zeichenfolge (Browser)
Importieren des Pakets
Um die Clients zu verwenden, importieren Sie das Paket in Ihre Datei:
const AzureStorageBlob = require("@azure/storage-blob");
Alternativ können Sie selektiv nur die Typen importieren, die Sie benötigen:
const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");
Erstellen des Blob-Dienstclients
Die BlobServiceClient
erfordert eine URL für den Blobdienst und zugriffsberechtigungen. Optional werden auch einige Einstellungen im options
Parameter akzeptiert.
mit DefaultAzureCredential
ab @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 - /azure/storage/common/storage-auth-aad-app
Registrieren einer neuen AAD-Anwendung und Erteilen von Berechtigungen für den Zugriff auf Azure Storage im Auftrag des angemeldeten Benutzers
- Registrieren einer neuen Anwendung in Azure Active Directory (im Azure-Portal): /azure/active-directory/develop/quickstart-register-app
- Wählen Sie im Abschnitt die
API permissions
Option ausAdd a permission
, und wählen Sie ausMicrosoft APIs
. - Aktivieren Sie
Azure Storage
das Kontrollkästchen neben,user_impersonation
und klicken Sie dann aufAdd 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
- RBAC-Rollen für Blobs und Warteschlangen: /azure/storage/common/storage-auth-aad-rbac-portal.
- Navigieren Sie im Azure-Portal zu Ihrem Speicherkonto, und weisen Sie der registrierten
Access control (IAM)
AAD-Anwendung über die Registerkarte die Rolle "Mitwirkender von Speicherblobdaten" zu (in der linken Navigationsleiste Ihres Speicherkontos im azure-Portal).
Umgebungseinrichtung für das Beispiel
- Notieren Sie sich auf der Übersichtsseite Ihrer AAD-Anwendung die
CLIENT ID
- undTENANT ID
. Erstellen Sie auf der Registerkarte "Zertifikate & Geheimnisse" ein Geheimnis, und notieren Sie sich dies. - Stellen Sie sicher, dass Sie über AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET als Umgebungsvariablen verfügen, um das Beispiel erfolgreich auszuführen(Kann process.env nutzen).
- Notieren Sie sich auf der Übersichtsseite Ihrer AAD-Anwendung die
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
);
Ein vollständiges Beispiel mit dieser Methode finden Sie im Azure AD-Authentifizierungsbeispiel .
[Hinweis : Die obigen Schritte sind nur für Node.js]
Verwenden von Verbindungszeichenfolge
Alternativ können Sie eine BlobServiceClient
instanziieren, indem Sie die fromConnectionString()
statische Methode mit der vollständigen Verbindungszeichenfolge als Argument verwenden. (Die Verbindungszeichenfolge kann über das Azure-Portal abgerufen werden.) [NUR IN NODE.JS RUNTIME VERFÜGBAR]
const { BlobServiceClient } = require("@azure/storage-blob");
const connStr = "<connection string>";
const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);
Mit StorageSharedKeyCredential
Alternativ instanziieren Sie ein BlobServiceClient
mit einem StorageSharedKeyCredential
, indem Sie kontoname und account-key als Argumente übergeben. (Der Kontoname und der Kontoschlüssel können über das Azure-Portal abgerufen werden.) [NUR IN NODE.JS RUNTIME VERFÜGBAR]
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
);
mit SAS-Token
Außerdem können Sie ein BlobServiceClient
mit einer SAS (Shared Access Signatures) instanziieren. Sie können das SAS-Token aus dem Azure-Portal abrufen oder mit generateAccountSASQueryParameters()
generieren.
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}`);
Erstellen eines neuen Containers
Verwenden Sie BlobServiceClient.getContainerClient()
, um eine Containerclientinstanz abzurufen und dann eine neue Containerressource zu erstellen.
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();
Auflisten der Container
Verwenden Sie BlobServiceClient.listContainers()
die Funktion, um die Container mit der neuen for-await-of
Syntax zu durchlaufen:
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();
Alternativ ohne :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;
let iter = blobServiceClient.listContainers();
let containerItem = await iter.next();
while (!containerItem.done) {
console.log(`Container ${i++}: ${containerItem.value.name}`);
containerItem = await iter.next();
}
}
main();
Darüber hinaus wird die Paginierung auch für die Auflistung über byPage()
unterstützt:
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();
Ein vollständiges Beispiel zum Durchlaufen von Containern finden Sie unter samples/v12/typescript/src/listContainers.ts.
Erstellen eines Blobs durch Hochladen von Daten
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();
Auflisten von Blobs in einem Container
Ähnlich wie das Auflisten von Containern.
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();
Ein vollständiges Beispiel zum Durchlaufen von Blobs finden Sie unter samples/v12/typescript/src/listBlobsFlat.ts.
Herunterladen eines Blobs und Konvertieren in eine Zeichenfolge (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();
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 Bundle .
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();
Ein vollständiges Beispiel für einfache Szenarien finden Sie unter samples/v12/typescript/src/sharedKeyAuth.ts.
Problembehandlung
Die Aktivierung der Protokollierung kann hilfreiche Informationen über Fehler aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die Umgebungsvariable AZURE_LOG_LEVEL
auf info
fest. Alternativ kann die Protokollierung zur Laufzeit aktiviert werden, indem Sie setLogLevel
in @azure/logger
aufrufen:
const { setLogLevel } = require("@azure/logger");
setLogLevel("info");
Nächste Schritte
Weitere Codebeispiele:
Mitwirken
Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie die Anleitung für Mitwirkende, um mehr darüber zu erfahren, wie Sie den Code erstellen und testen können.
Weitere Informationen zum Einrichten der Testumgebung für Speicherbibliotheken finden Sie auch im Speicherspezifischen Leitfaden .
Azure SDK for JavaScript
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unterFeedback senden und anzeigen für