Verwenden von Azure-Clientbibliotheken für JavaScript und TypeScript

Artikel
08/30/2024

Verwenden Sie die Azure-Clientbibliotheken für JavaScript, um programmgesteuert auf Ihre Azure-Dienste zuzugreifen. In der Regel gelten diese Bibliotheken für den @azure-npm-Paketbereich, der von azure-sdk veröffentlicht wird.

Unterschiede zwischen Clientbibliotheken und REST-APIs

Anhand der folgenden Informationen können Sie nachvollziehen, wann welche Art von Zugriff verwendet werden soll:

Die Azure-Clientbibliotheken sind die bevorzugte Methode für den Zugriff auf Ihren Azure-Dienst. Diese Bibliotheken abstrahieren die Codebausteine, die zum Verwalten cloudbasierter REST-Anforderungen (etwa Authentifizierung, Wiederholungen und Protokollierung) der Azure-Plattform erforderlich sind.
Azure-REST-APIs sind in folgenden Fällen die bevorzugte Methode:
- Sie arbeiten mit Vorschaudiensten, für die keine Azure-Clientbibliotheken verfügbar sind. Betrachten Sie Ihren Code als Vorschauversion, die aktualisiert werden sollte, wenn der Dienst allgemein mit Clientbibliotheken verfügbar ist.
- Sie möchten REST-Aufrufe direkt durchführen, da Sie nicht möchten, dass das gesamte SDK eine einzelne REST-API verwendet, oder Sie möchten genauere Kontrolle über die HTTP-Anforderungen.

Client- und Verwaltungsbibliotheken von Azure

Folgende Versionen der Azure-Clientbibliothek sind verfügbar:

Verwaltung: Mithilfe von Verwaltungsbibliotheken können Sie Azure-Ressourcen erstellen und verwalten. Diese Bibliotheken erkennen Sie anhand von arm- im jeweiligen Paketnamen. Der Begriff „ARM“ steht für „Azure Resource Manager“.
- Dokumentation und Codebeispiele
Client: Wenn bereits eine Azure-Ressource vorhanden ist, verwenden Sie die Clientbibliotheken, um sie zu nutzen und mit ihr zu interagieren.
- Jede Paketdatei vom Typ „README.md“ enthält eine Dokumentation und Beispiele.

Installieren von Azure-npm-Paketen

Azure-Clientbibliotheken sind kostenlos über NPM verfügbar. Installieren Sie bei Bedarf einzelne SDKs. Jedes SDK stellt TypeScript-Definitionen bereit.

Für die Client-/Browsernutzung müssen Ihrem Bündelungsprozess Azure-Clientbibliotheken hinzugefügt werden.

Verwenden des Beispielcodes aus Azure-npm-Paketen

Jedes Paket enthält eine Dokumentation, die Ihnen schnell erste Schritte mit dem Paket ermöglicht. Informationen zur Verwendung finden Sie in den jeweiligen von Ihnen verwendeten NPM-Paketen.

Angeben von Anmeldeinformationen für die Authentifizierung

Für die Azure-Clientbibliotheken sind Anmeldeinformationen für die Authentifizierung bei der Azure-Plattform erforderlich. Anmeldeinformationsklassen, bereitgestellt von @azure/identity, bieten verschiedene Vorteile:

Schnelles Onboarding
Sicherste Methode
Trennen des Authentifizierungsmechanismus vom Code. Dadurch können Sie denselben Code lokal und auf der Azure-Plattform verwenden, obwohl sich die Anmeldeinformationen unterscheiden.
Bereitstellen einer verketteten Authentifizierung, sodass mehrere Mechanismen zur Verfügung stehen können

Erstellen eines SDK-Clients und Aufrufen von Methoden

Nachdem Sie programmgesteuert Anmeldeinformationen erstellt haben, übergeben Sie die Anmeldeinformationen an Ihren Azure-Client. Der Client benötigt möglicherweise zusätzliche Informationen, z. B. eine Abonnement-ID oder einen Dienstendpunkt. Diese Werte sind im Azure-Portal für Ihre Ressource verfügbar.

Im folgenden Codebeispiel werden DefaultAzureCredential und die arm-Abonnementclientbibliothek zum Auflisten von Abonnements verwendet, auf die diese Anmeldeinformationen Lesezugriff haben.

const {
  ClientSecretCredential,
  DefaultAzureCredential,
} = require("@azure/identity");
const { SubscriptionClient } = require("@azure/arm-subscriptions");
require("dotenv").config();

let credentials = null;

const tenantId = process.env["AZURE_TENANT_ID"];
const clientId = process.env["AZURE_CLIENT_ID"];
const secret = process.env["AZURE_CLIENT_SECRET"];

if (process.env.NODE_ENV && process.env.NODE_ENV === "production") {
  // production
  credentials = new DefaultAzureCredential();
} else {
  // development
  if (tenantId && clientId && secret) {
    console.log("development");
    credentials = new ClientSecretCredential(tenantId, clientId, secret);
  } else {
    credentials = new DefaultAzureCredential();
  }
}

async function listSubscriptions() {
  try {
    // use credential to authenticate with Azure SDKs
    const client = new SubscriptionClient(credentials);

    // get details of each subscription
    for await (const item of client.subscriptions.list()) {
      const subscriptionDetails = await client.subscriptions.get(
        item.subscriptionId
      );
      /* 
        Each item looks like:
      
        {
          id: '/subscriptions/123456',
          subscriptionId: '123456',
          displayName: 'YOUR-SUBSCRIPTION-NAME',
          state: 'Enabled',
          subscriptionPolicies: {
            locationPlacementId: 'Internal_2014-09-01',
            quotaId: 'Internal_2014-09-01',
            spendingLimit: 'Off'
          },
          authorizationSource: 'RoleBased'
        },
    */
      console.log(subscriptionDetails);
    }
  } catch (err) {
    console.error(JSON.stringify(err));
  }
}

listSubscriptions()
  .then(() => {
    console.log("done");
  })
  .catch((ex) => {
    console.log(ex);
  });

Asynchrones Auslagern von Ergebnissen

Eine SDK-Methode kann einen asynchronen Iterator (PagedAsyncIterableIterator) zurückgeben, um asynchrone Ergebnisse zu ermöglichen. Die Ergebnisse können Auslagerungs- und Fortsetzungstoken verwenden, um Resultsets aufzuteilen.

Im folgenden JavaScript-Beispiel wird die asynchrone Auslagerung veranschaulicht. Der Code legt eine künstlich kurze Auslagerungsgröße von 2 fest, um den Prozess schnell und visuell zu veranschaulichen, wenn Sie den Beispielcode beim Debuggen ausführen.

const { BlobServiceClient } = require("@azure/storage-blob");

const blobAccountConnectionString = "REPLACE-WITH-YOUR-STORAGE-CONNECTION-STRING";
const blobAccountContainerName = "REPLACE-WITH-YOUR-STORAGE-CONTAINER-NAME";

const pageSize = 2;

const list = async () => {

  console.log(`List`);

  let continuationToken = "";
  let currentPage = 1;
  let containerClient=null;
  let currentItem = 1;

  // Get Blob Container - need to have items in container before running this code
  const blobServiceClient = BlobServiceClient.fromConnectionString(blobAccountConnectionString);
  containerClient = blobServiceClient.getContainerClient(blobAccountContainerName);

  do {

    // Get Page of Blobs
    iterator = (continuationToken != "") 
      ? containerClient.listBlobsFlat().byPage({ maxPageSize: pageSize, continuationToken }) 
      : containerClient.listBlobsFlat().byPage({ maxPageSize: pageSize });
    
    page = (await iterator.next()).value;

    // Display list
    if (page.segment?.blobItems) {
      console.log(`\tPage [${currentPage}] `);
      for (const blob of page.segment.blobItems) {
        console.log(`\t\tItem [${currentItem++}] ${blob.name}`);
      }
    };

    // Move to next page
    continuationToken = page.continuationToken;
    if (continuationToken) {
      currentPage++;
    }

  } while (continuationToken != "")
}

list(() => {
  console.log("done");
}).catch((ex) =>
  console.log(ex)
);

Erfahren Sie mehr über Auslagerung und Iteratoren in Azure:

Asynchrone Iteratoren im Azure SDK für JavaScript/TypeScript

Vorgänge mit langer Ausführung

Eine SDK-Methode kann eine unformatierte Antwort vom Typ „Zeitintensiver Vorgang“ (Long Running Operation, LRO) zurückgeben. Diese Antwort enthält u. a. folgende Informationen:

Ihre Anforderung ist abgeschlossen.
Ihre Anforderung wird noch verarbeitet.

Im folgenden JavaScript-Beispiel wird veranschaulicht, wie Sie mit .pollUntildone() auf den Abschluss eines LRO warten, bevor Sie fortfahren:

const { BlobServiceClient } = require("@azure/storage-blob");

const blobAccountConnectionString = "REPLACE-WITH-YOUR-STORAGE-CONNECTION-STRING";
const blobAccountContainerName = `test-${Date.now().toString()}`;

const files = [
  {
    "url": "https://github.com/Azure/azure-sdk-for-js/blob/main/README.md",
    "fileName": "README.md"
  },
  {
    "url": "https://github.com/Azure/azure-sdk-for-js/blob/main/gulpfile.ts",
    "fileName": "gulpfile.ts"
  },
  {
    "url": "https://github.com/Azure/azure-sdk-for-js/blob/main/rush.json",
    "fileName": "rush.json"
  },  
  {
    "url": "https://github.com/Azure/azure-sdk-for-js/blob/main/package.json",
    "fileName": "package.json"
  },
  {
    "url": "https://github.com/Azure/azure-sdk-for-js/blob/main/tsdoc.json",
    "fileName": "tsdoc.json"
  },
];

const upload = async() => {

  // get container client
  const blobServiceClient = BlobServiceClient.fromConnectionString(blobAccountConnectionString);

  // get container's directory client
  const containerClient = blobServiceClient.getContainerClient(blobAccountContainerName);

  files.forEach(async(file) =>{
    await (

      await containerClient
        .getBlobClient(file.fileName)
        .beginCopyFromURL(file.url)
  
    ).pollUntilDone();
  })
}

upload(() => {
  console.log("done");
}).catch((ex) =>
  console.log(ex)
);

Weitere Informationen zu zeitintensiven Vorgängen in Azure finden Sie unter folgendem Link:

@azure/core-lro

Abbrechen asynchroner Vorgänge

Das @azure/abort-controller-Paket stellt die Klassen „AbortController“ und „AbortSignal“ bereit. Verwenden Sie AbortController, um ein Abbruchsignal (AbortSignal) zu erstellen, das dann an Azure SDK-Vorgänge übergeben werden kann, um ausstehende Aufgaben abzubrechen. Beispiele für Azure SDK-Vorgänge:

Basierend auf Ihrer eigenen Logik abgebrochen
Basierend auf einem Timeoutgrenzwert abgebrochen
Basierend auf dem Signal einer übergeordneten Aufgabe abgebrochen
Basierend auf dem Signal einer übergeordneten Aufgabe oder basierend auf einem Timeoutgrenzwert abgebrochen

Weitere Informationen:

Verwenden von Abbruchsignalen zum Abbrechen von Vorgängen im Azure SDK für JavaScript/TypeScript

Ausführliche Protokollierung über das SDK

Wenn Sie ein Azure SDK verwenden, kann es vorkommen, dass Sie Ihre Anwendung debuggen müssen.

Wenn Sie die Protokollierung zur Buildzeit aktivieren möchten, legen Sie die Umgebungsvariable AZURE_LOG_LEVEL auf info fest.
Verwenden Sie zum Aktivieren der Protokollierung zur Laufzeit das Paket @azure/logger:
```
import { setLogLevel } from "@azure/logger";

setLogLevel("info");
```

Bündelung

Erfahren Sie mehr über die Bündelung mit dem Azure SDK:

Freigeben über