Erste Schritte mit Azure Blob Storage und JavaScript

• .NET
• Java
• JavaScript
• TypeScript
• Python

In diesem Artikel erfahren Sie, wie Sie mithilfe der Azure Blob Storage-Clientbibliothek v12 für JavaScript eine Verbindung mit Azure Blob Storage herstellen. Nach der Verbindung kann Ihr Code Container, Blobs und Features des Blob Storage-Diensts verwenden.

Die Beispielcodeausschnitte sind in GitHub als ausführbare Node.js-Dateien verfügbar.

API-Referenz | Paket (npm) | Quellcode der Bibliothek | Beispiele | Feedback geben

Voraussetzungen

• Azure-Abonnement – Erstellen eines kostenlosen Kontos
• Azure Storage-Konto – Erstellen eines Speicherkontos
• Node.js LTS
• Für Clientanwendungen (Browser) benötigen Sie Bündelungstools.

Einrichten des Projekts

1. Öffnen Sie eine Eingabeaufforderung, und wechseln Sie in Ihren Projektordner. Ändern Sie YOUR-DIRECTORY in den Ordnernamen:

   cd YOUR-DIRECTORY
   

2. Wenn Sie noch keine package.json-Datei in Ihrem Verzeichnis haben, initialisieren Sie das Projekt, um die Datei zu erstellen:

   npm init -y
   

3. Installieren Sie die Azure Blob Storage-Clientbibliothek für JavaScript:

   npm install @azure/storage-blob
   

4. Wenn Sie kennwortlose Verbindungen mit Microsoft Entra ID verwenden möchten, installieren Sie die Azure Identity-Clientbibliothek für JavaScript:

   npm install @azure/identity
   

Autorisieren des Zugriffs und Herstellen einer Verbindung mit Blob Storage

Microsoft Entra ID bietet die sicherste Verbindung, durch die Verwaltung der Verbindungsidentität (verwaltete Identität). Mit der kennwortlosen Funktionalität können Sie eine Anwendung entwickeln, die keine Speicherung von Geheimnissen (Schlüsseln oder Verbindungszeichenfolgen) im Code erfordert.

Einrichten des Identitätszugriffs auf die Azure Cloud

Um ohne Kennwörter eine Verbindung mit Azure herzustellen, müssen Sie eine Azure-Identität einrichten oder eine vorhandene Identität verwenden. Nachdem die Identität eingerichtet wurde, stellen Sie sicher, dass Sie der Identität die entsprechenden Rollen zuweisen.

Um den kennwortlosen Zugriff mit der Microsoft Entra ID zu autorisieren, müssen Sie Azure-Anmeldeinformationen verwenden. Welche Art von Anmeldeinformation Sie benötigen, hängt davon ab, wo Ihre Anwendung ausgeführt wird. Verwenden Sie diese Tabelle als Richtlinie.

Environment	Methode
Entwicklerumgebung	Visual Studio Code
Entwicklerumgebung	Dienstprinzipal
Von Azure gehostete Apps	Einrichtung Azure-gehosteter Apps
Lokal	Einrichtung lokaler Apps

Einrichten von Speicherkontorollen

Für Ihre Speicherressource muss mindestens eine der folgenden Azure RBAC-Rollen derjenigen Identitätsressource zugewiesen werden, mit der Sie eine Verbindung herstellen möchten. Richten Sie die Azure Storage-Rollen für jede Identität ein, die Sie im vorherigen Schritt erstellt haben: „Azure Cloud“, „Lokale Entwicklung“, „Lokal“.

Nachdem Sie die Einrichtung abgeschlossen haben, benötigt jede Identität mindestens eine geeignete Rolle:

• Eine Datenzugriffsrolle, z. B.:

  • Leser von Speicherblobdaten
  • Mitwirkender an Speicherblobdaten

• Eine Ressourcenrolle, z. B.:

  • Leser
  • Mitwirkender

Erstellen Ihrer Anwendung

Wenn Sie Ihre Anwendung erstellen, interagiert Ihr Code in erster Linie mit drei Arten von Ressourcen:

• Dem Speicherkonto, welches den eindeutigen Namespace der obersten Ebene für Ihre Azure Storage-Daten darstellt.
• Container, die die Blobdaten in Ihrem Speicherkonto organisieren.
• Blobs, die unstrukturierte Daten wie Text- und Binärdaten speichern.

Im folgenden Diagramm ist die Beziehung zwischen diesen Ressourcen dargestellt.

Jeder Ressourcentyp wird durch eine oder mehrere zugeordnete JavaScript-Clients dargestellt:

Klasse	BESCHREIBUNG
BlobServiceClient	Stellt den Blob-Storage-Endpunkt für Ihr Speicherkonto dar.
ContainerClient	Erlaubt Ihnen das Bearbeiten von Azure Storage-Containern und deren Blobs.
BlobClient	Erlaubt Ihnen das Bearbeiten von Azure Storage-Blobs.

Erstellen des Objekts BlobServiceClient

Das BlobServiceClient-Objekt ist das oberste Objekt im SDK. Mit diesem Client können Sie den Dienst, Container und Blobs bearbeiten.

Kennwortlos

Nachdem Ihre Identitätsrollen für Ihr Azure Storage-Konto und Ihre lokale Umgebung eingerichtet wurden, erstellen Sie eine JavaScript-Datei, die das Paket @azure/identity enthält. Erstellen Sie Anmeldeinformationen, z. B. DefaultAzureCredential, um kennwortlose Verbindungen mit Blob Storage zu implementieren. Authentifizieren Sie sich mit diesen Anmeldeinformationen beim Objekt BlobServiceClient.

// connect-with-default-azure-credential.js
const { BlobServiceClient } = require('@azure/storage-blob');
const { DefaultAzureCredential } = require('@azure/identity');
require('dotenv').config()

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error('Azure Storage accountName not found');

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

async function main(){
  
  const containerName = 'REPLACE-WITH-EXISTING-CONTAINER-NAME';
  const blobName = 'REPLACE-WITH-EXISTING-BLOB-NAME';

  const timestamp = Date.now();
  const fileName = `my-new-file-${timestamp}.txt`;

  // create container client
  const containerClient = await blobServiceClient.getContainerClient(containerName);

  // create blob client
  const blobClient = await containerClient.getBlockBlobClient(blobName);

  // download file
  await blobClient.downloadToFile(fileName);

  console.log(`${fileName} downloaded`);
  
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(`error: ${ex.message}`));

Das Paket dotenv wird verwendet, um den Namen Ihres Speicherkontos aus einer .env-Datei zu lesen. Diese Datei sollte nicht in die Quellcodeverwaltung eingecheckt werden. Wenn Sie einen lokalen Dienstprinzipal als Teil Ihrer DefaultAzureCredential-Einrichtung verwenden, werden alle Sicherheitsinformationen für diese Anmeldeinformationen auch in der .env-Datei gespeichert.

Wenn Sie planen, die Anwendung auf außerhalb von Azure betriebenen Servern und Clients bereitzustellen, erstellen Sie eine der Arten von Anmeldeinformationen, die Ihren Anforderungen entspricht.

Kontoschlüssel

Erstellen Sie mithilfe des Speicherkontonamens und des Kontoschlüssels ein Element des Typs StorageSharedKeyCredential. Übergeben Sie StorageSharedKeyCredential an den Klassenkonstruktor BlobServiceClient, um einen Client zu erstellen.

// connect-with-account-name-and-key.js
const { BlobServiceClient, StorageSharedKeyCredential } = require('@azure/storage-blob');
require('dotenv').config()

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountName) throw Error('Azure Storage accountName not found');
if (!accountKey) throw Error('Azure Storage accountKey not found');

const sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);

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

async function main() {

  const containerName = 'REPLACE-WITH-EXISTING-CONTAINER-NAME';
  const blobName = 'REPLACE-WITH-EXISTING-BLOB-NAME';

  const timestamp = Date.now();
  const fileName = `my-new-file-${timestamp}.txt`;

  // create container client
  const containerClient = await blobServiceClient.getContainerClient(containerName);

  // create blob client
  const blobClient = await containerClient.getBlockBlobClient(blobName);

  // download file
  await blobClient.downloadToFile(fileName);

  console.log(`${fileName} downloaded`);

}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

Das Paket dotenv wird verwendet, um den Namen und Schlüssel Ihres Speicherkontos aus einer .env-Datei zu lesen. Diese Datei sollte nicht in die Quellcodeverwaltung eingecheckt werden.

Informationen zum Abrufen von Kontoschlüsseln und Best Practices-Richtlinien für die ordnungsgemäße Verwaltung und Sicherung Ihrer Schlüssel finden Sie unter Verwalten von Speicherkonto-Zugriffsschlüsseln.

SAS-Token

Erstellen Sie einen URI zu Ihrer Ressource mithilfe des Blob-Dienstendpunkts und des SAS-Tokens. Erstellen Sie dann mit dem URI einen BlobServiceClient. Das SAS-Token besteht aus einer Reihe von Name-Wert-Paaren in der Abfragezeichenfolge im folgenden Format:

https://YOUR-RESOURCE-NAME.blob.core.windows.net?YOUR-SAS-TOKEN

Je nachdem, welches Tool Sie zum Generieren Ihres SAS-Tokens verwenden, wurde die Abfragezeichenfolge ? möglicherweise bereits dem SAS-Token hinzugefügt.

// connect-with-sas-token.js
const { BlobServiceClient } = require('@azure/storage-blob');
require('dotenv').config()

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
const sasToken = process.env.AZURE_STORAGE_SAS_TOKEN;
if (!accountName) throw Error('Azure Storage accountName not found');
if (!sasToken) throw Error('Azure Storage accountKey not found');

const blobServiceUri = `https://${accountName}.blob.core.windows.net`;

// https://YOUR-RESOURCE-NAME.blob.core.windows.net?YOUR-SAS-TOKEN
const blobServiceClient = new BlobServiceClient(
  `${blobServiceUri}?${sasToken}`,
  null
);

async function main(){
  
  const containerName = 'REPLACE-WITH-EXISTING-CONTAINER-NAME';
  const blobName = 'REPLACE-WITH-EXISTING-BLOB-NAME';

  const timestamp = Date.now();
  const fileName = `my-new-file-${timestamp}.txt`;

  // create container client
  const containerClient = await blobServiceClient.getContainerClient(containerName);

  // create blob client
  const blobClient = await containerClient.getBlockBlobClient(blobName);

  // download file
  await blobClient.downloadToFile(fileName);

  console.log(`${fileName} downloaded`);
  
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(`error: ${ex.message}`));

Das Paket dotenv wird verwendet, um den Namen und das SAS-Token Ihres Speicherkontos aus einer .env-Datei zu lesen. Diese Datei sollte nicht in die Quellcodeverwaltung eingecheckt werden.

Informationen zum Generieren und Verwalten von SAS-Token finden Sie in den folgenden Artikeln:

• Gewähren von eingeschränktem Zugriff auf Azure Storage-Ressourcen mithilfe von SAS (Shared Access Signature)

• Erstellen einer Dienst-SAS für einen Container oder ein Blob

Erstellen des Objekts ContainerClient

Sie können das Objekt ContainerClient entweder anhand von BlobServiceClient oder direkt erstellen.

Erstellen des Objekts ContainerClient anhand von BlobServiceClient

Erstellen Sie das Objekt ContainerClient anhand von BlobServiceClient.

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

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountKey) throw Error("Azure Storage accountKey not found");

// Create credential
const sharedKeyCredential = new StorageSharedKeyCredential(
  accountName,
  accountKey
);

const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;

// Create BlobServiceClient
const blobServiceClient = new BlobServiceClient(
  `${baseUrl}`,
  sharedKeyCredential
);

async function main() {
  try {
    // Create container client
    const containerClient = await blobServiceClient.getContainerClient(
      containerName
    );

    // do something with containerClient...
    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
      console.log(`Blob ${i++}: ${blob.name}`);
    }
  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

Direktes Erstellen von ContainerClient

Kennwortlos

// Azure Storage dependency
const {
  ContainerClient
} = require("@azure/storage-blob");

// Azure authentication for credential dependency
const { DefaultAzureCredential } = require('@azure/identity');

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure SDK needs base URL
const baseUrl = `https://${accountName}.blob.core.windows.net`;

// Unique container name
const timeStamp = Date.now();
const containerName = `test`;

async function main() {
  try {
    
    // create container client from DefaultAzureCredential
    const containerClient = new ContainerClient(
      `${baseUrl}/${containerName}`,
      new DefaultAzureCredential()
    );    

    // do something with containerClient...
    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
        console.log(`Blob ${i++}: ${blob.name}`);
    }


  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

Kontoschlüssel

// Azure Storage dependency
const {
  StorageSharedKeyCredential,
  ContainerClient
} = require("@azure/storage-blob");

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountKey) throw Error("Azure Storage accountKey not found");

const sharedKeyCredential = new StorageSharedKeyCredential(
  accountName,
  accountKey
);

const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;

async function main() {
  try {
    // create container from ContainerClient
    const containerClient = new ContainerClient(
      `${baseUrl}/${containerName}`,
      sharedKeyCredential
    );    

    // do something with containerClient...
    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
        console.log(`Blob ${i++}: ${blob.name}`);
    }
    

  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

SAS-Token

// Azure Storage dependency
const {
  ContainerClient
} = require("@azure/storage-blob");

// For development environment - include environment variables
require("dotenv").config();

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Container must exist prior to running this script
const containerName = `test`;

// SAS token must have LIST permissions on container that haven't expired
const sasToken = process.env.AZURE_STORAGE_SAS_TOKEN;

// Create SAS URL
const sasUrl = `https://${accountName}.blob.core.windows.net/${containerName}?${sasToken}`;

async function main() {
  try {
    // create container client from SAS token
    const containerClient = new ContainerClient(sasUrl);

    // do something with containerClient...
    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
        console.log(`Blob ${i++}: ${blob.name}`);
    }   
    
  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

Das Paket dotenv wird verwendet, um den Namen Ihres Speicherkontos aus einer .env-Datei zu lesen. Diese Datei sollte nicht in die Quellcodeverwaltung eingecheckt werden.

Erstellen des Objekts BlobClient

Sie können jedes der unten aufgeführten Objekte des Typs BlobClient entweder anhand von ContainerClient oder direkt erstellen.

Liste der Blobclients:

• BlobClient
• BlockBlobClient
• AppendBlobClient
• BlobLeaseClient
• PageBlobClient

Erstellen des Objekts BlobClient anhand von ContainerClient

// Azure Storage dependency
const {
  StorageSharedKeyCredential,
  ContainerClient
} = require("@azure/storage-blob");

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountKey) throw Error("Azure Storage accountKey not found");

// Create credential
const sharedKeyCredential = new StorageSharedKeyCredential(
  accountName,
  accountKey
);

const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;
const blobName = `my-blob`;

// Create ContainerClient
const containerClient = new ContainerClient(
  `${baseUrl}/${containerName}`,
  sharedKeyCredential
);  

async function main() {
  try {
  
    // Create BlobClient object
    const blobClient = containerClient.getBlobClient(blobName);

    // do something with blobClient...
    const properties = await blobClient.getProperties();
    console.log(`Blob ${blobName} properties:`);

    // get BlockBlobClient from blobClient
    const blockBlobClient = blobClient.getBlockBlobClient();

    // do something with blockBlobClient...
    const downloadResponse = await blockBlobClient.download(0);

  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

Direktes Erstellen von BlobClient

Kennwortlos

// Azure Storage dependency
const { BlockBlobClient } = require("@azure/storage-blob");

// Azure authentication for credential dependency
const { DefaultAzureCredential } = require('@azure/identity');

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure SDK needs base URL
const baseUrl = `https://${accountName}.blob.core.windows.net`;

// Container must exist prior to running this script
const containerName = `test`;

// Random blob name and contents
const timeStamp = Date.now();
const blobName = `${timeStamp}-my-blob.txt`;
const fileContentsAsString = "Hello there.";

async function main(){

  // Create a client that can authenticate with Azure Active Directory
  const client = new BlockBlobClient(
    `${baseUrl}/${containerName}/${blobName}`,
    new DefaultAzureCredential()
  );

  // Get file url - available before contents are uploaded
  console.log(`blob.url: ${client.url}`);

  // Upload file contents
  const result = await client.upload(fileContentsAsString, fileContentsAsString.length);

  // Get results
  return result;
}

main().then((result) => console.log(result)).catch((ex) => console.log(ex.message));

/*

Response looks like this:

{
  etag: '"0x8DAD247F1F4896E"',
  lastModified: 2022-11-29T20:26:07.000Z,
  contentMD5: <Buffer 9d 6a 29 63 87 20 77 db 67 4a 27 a3 9c 49 2e 61>,
  clientRequestId: 'a07fdd1f-5937-44c7-984f-0699a48a05c0',
  requestId: '3580e726-201e-0045-1a30-0474f6000000',
  version: '2021-04-10',
  date: 2022-11-29T20:26:06.000Z,
  isServerEncrypted: true,
  'content-length': '0',
  server: 'Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0',
  'x-ms-content-crc64': 'BLv7vb1ONT8=',
  body: undefined
}
*/

Kontoschlüssel

// Azure Storage dependency
const {
  StorageSharedKeyCredential,
  BlockBlobClient,
} = require("@azure/storage-blob");

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountKey) throw Error("Azure Storage accountKey not found");

// Create credential
const sharedKeyCredential = new StorageSharedKeyCredential(
  accountName,
  accountKey
);

const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;
const blobName = `my-blob`;

const fileContentsAsString = "Hello there.";

async function main() {
  try {

    // create blob from BlockBlobClient
    const blockBlobClient = new BlockBlobClient(
      `${baseUrl}/${containerName}/${blobName}`,
      sharedKeyCredential
    );

    // Upload data to the blob  
    await blockBlobClient.upload(
      fileContentsAsString,
      fileContentsAsString.length
    );
    console.log(`blob ${blockBlobClient.url} created`);
  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

SAS-Token

// Azure Storage dependency
const { BlockBlobClient } = require("@azure/storage-blob");

// For development environment - include environment variables
require("dotenv").config();

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Container and blob must exist prior to running this script
// SAS token must have READ permissions on blob that haven't expired
const containerName = `test`;
const blobName = `my-text-file.txt`;

// Create SAS URL
const sasToken = process.env.AZURE_STORAGE_SAS_TOKEN;
const sasUrl = `https://${accountName}.blob.core.windows.net/${containerName}/${blobName}?${sasToken}`;

// Utility function to convert 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);
  });
}

async function main(){

  // Create a blob client from SAS token
  const client = new BlockBlobClient(sasUrl);

  // Get blob url
  console.log(`blob.url: ${client.url}`);

  // Download file contents
  const result = await client.download();
  const content = await streamToBuffer(result.readableStreamBody);

  // Get results
  return content.toString();
}

main().then((result) => console.log(result)).catch((ex) => console.log(ex.message));

Das Paket dotenv wird verwendet, um den Namen Ihres Speicherkontos aus einer .env-Datei zu lesen. Diese Datei sollte nicht in die Quellcodeverwaltung eingecheckt werden.

Siehe auch

• Paket (npm)
• Beispiele
• API-Referenz
• Quellcode der Bibliothek
• Feedback geben