Teilen über

Erste Schritte mit Azure Blob Storage und TypeScript

  • Artikel

In diesem Artikel erfahren Sie, wie Sie mithilfe der Azure Blob Storage-Clientbibliothek 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.

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

Voraussetzungen

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 TypeScript und die Azure Blob Storage Clientbibliothek für JavaScript mit TypeScript-Typen:

    npm install typescript @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:

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.

Diagramm der Blob Storage-Architektur

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.

Nachdem Ihre Identitätsrollen für Ihr Azure Storage-Konto und Ihre lokale Umgebung eingerichtet wurden, erstellen Sie eine TypeScript-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
// You must set up RBAC for your identity with one of the following roles:
// - Storage Blob Data Reader
// - Storage Blob Data Contributor
import { DefaultAzureCredential } from '@azure/identity';
import { BlobServiceClient } from '@azure/storage-blob';
import * as dotenv from 'dotenv';
dotenv.config();

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME as string;
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 = 'my-container';
  const blobName = 'my-blob';

  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
  const downloadResult = await blobClient.downloadToFile(fileName);

  if (downloadResult.errorCode) throw Error(downloadResult.errorCode);

  console.log(
    `${fileName} downloaded ${downloadResult.contentType}, isCurrentVersion: ${downloadResult.isCurrentVersion}`
  );
}

main()
  .then(() => console.log(`success`))
  .catch((err: unknown) => {
    if (err instanceof Error) {
      console.log(err.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.

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
import {
  BlobServiceClient,
  StorageSharedKeyCredential
} from '@azure/storage-blob';

// For development environment - include environment variables from .env
import * as dotenv from 'dotenv';
dotenv.config();

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

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY as string;
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(): Promise<void> {
  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({
      includeMetadata: true,
      includeSnapshots: false,
      includeTags: true,
      includeVersions: false,
      prefix: ''
    })) {
      console.log(`Blob ${i++}: ${blob.name}`);
    }
  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`success`))
  .catch((err: unknown) => {
    if (err instanceof Error) {
      console.log(err.message);
    }
  });

Direktes Erstellen von ContainerClient

// Azure Storage dependency
import { ContainerClient } from '@azure/storage-blob';

// Azure authentication for credential dependency
import { DefaultAzureCredential } from '@azure/identity';

// For development environment - include environment variables from .env
import * as dotenv from 'dotenv';
dotenv.config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME as string;
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 = `my-container`;

async function main(): Promise<void> {
  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({
      includeMetadata: true,
      includeSnapshots: false,
      includeTags: true,
      includeVersions: false,
      prefix: ''
    })) {
      console.log(`Blob ${i++}: ${blob.name}`);
    }
  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`success`))
  .catch((err: unknown) => {
    if (err instanceof Error) {
      console.log(err.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:

Erstellen des Objekts BlobClient anhand von ContainerClient

// Azure Storage dependency
import {
  BlobClient,
  BlobDownloadHeaders,
  BlobGetPropertiesHeaders,
  BlobGetPropertiesResponse,
  BlockBlobClient,
  ContainerClient
} from '@azure/storage-blob';

// For development environment - include environment variables from .env
import * as dotenv from 'dotenv';
import { getContainerClientFromDefaultAzureCredential } from './auth-get-client';
dotenv.config();

const containerName = `my-container`;
const containerClient: ContainerClient =
  getContainerClientFromDefaultAzureCredential(containerName);

const blobName = `my-blob`;

async function main(containerClient: ContainerClient): Promise<void> {
  // Create BlobClient object
  const blobClient: BlobClient = containerClient.getBlobClient(blobName);

  // do something with blobClient...
  const properties: BlobGetPropertiesHeaders = await blobClient.getProperties();
  if (properties.errorCode) throw Error(properties.errorCode);

  console.log(`Blob ${blobName} properties:`);

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

  // do something with blockBlobClient...
  const downloadResponse: BlobDownloadHeaders = await blockBlobClient.download(
    0
  );
  if (downloadResponse.errorCode) throw Error(downloadResponse.errorCode);
}

main(containerClient)
  .then(() => console.log(`success`))
  .catch((err: unknown) => {
    if (err instanceof Error) {
      console.log(err.message);
    }
  });

Direktes Erstellen von BlobClient

// Azure Storage dependency
import {
  BlockBlobClient,
  BlockBlobUploadHeaders,
  BlockBlobUploadResponse
} from '@azure/storage-blob';
import { getBlockBlobClientFromDefaultAzureCredential } from './auth-get-client';

// For development environment - include environment variables from .env
import * as dotenv from 'dotenv';
dotenv.config();

// Container must exist prior to running this script
const containerName = `my-container`;

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

const blockBlobClient: BlockBlobClient =
  getBlockBlobClientFromDefaultAzureCredential(containerName, blobName);

async function main(
  blockBlobClient: BlockBlobClient
): Promise<BlockBlobUploadHeaders> {
  // Get file url - available before contents are uploaded
  console.log(`blob.url: ${blockBlobClient.url}`);

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

  if (result.errorCode) throw Error(result.errorCode);

  // Get results
  return result;
}

main(blockBlobClient)
  .then((result) => {
    console.log(result);
    console.log(`success`);
  })
  .catch((err: unknown) => {
    if (err instanceof Error) {
      console.log(err.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
}
*/

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