Verwenden der Azure SDKs für JavaScript und TypeScript

Verwenden Sie die Azure SDKs für JavaScript, um programmgesteuert auf Ihre Azure-Dienste zuzugreifen. In der Regel werden diese SDKs auf den @azure npm-Paketbereich festgelegt, der von azure-sdk veröffentlicht wurde.

Unterschiede zwischen SDKs und REST-APIs

Verwenden Sie die folgenden Informationen, um zu verstehen, wann welche Art von Zugriffsmechanismus verwendet werden soll.

• Die Azure SDKs sind die bevorzugte Methode für den Zugriff auf Ihren Azure-Dienst. Die Azure SDKs abstrahieren die Codebausteine, die zum Verwalten cloudbasierter REST-Anforderungen (etwa Authentifizierung, Wiederholungen und Protokollierung) der Azure-Plattform erforderlich sind.
• Azure REST-APIs sind die bevorzugte Methode, wenn Sie:
  • Sie arbeiten mit Vorschaudiensten, für die keine Azure SDKs verfügbar sind. Betrachten Sie Ihren Code als Vorschauversion, die aktualisiert werden sollte, wenn der Dienst allgemein mit SDKs 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

Die Azure SDK-Releases sind verfügbar als:

• Verwaltungs-SDKs: Verwaltungsbibliotheken ermöglichen Ihnen die Bereitstellung und Verwaltung von Azure-Ressourcen über Azure Resource Manager (ARM). Diese Bibliotheken erkennen Sie anhand von @azure/arm- im jeweiligen Paketnamen.
  • Dokumentation und Codebeispiele
• Client-SDKs: 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 SDKs sind kostenlos über NPM verfügbar. Installieren Sie die einzelnen erforderlichen SDKs. Jedes SDK stellt TypeScript-Definitionen bereit.

Für die Client-/Browsernutzung müssen Ihrem Bündelungsprozess Azure SDKs 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

Die Azure SDKs erfordern Anmeldeinformationen für die Authentifizierung bei der Azure-Plattform. Anmeldeinformationsklassen , die von @azure/Identität bereitgestellt werden, bieten mehrere 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 den Client Ihres Azure SDK. Der Client benötigt möglicherweise zusätzliche Informationen, z. B. eine Abonnement-ID oder Dienst-URL. Diese Werte sind im Azure-Portal für Ihre Ressource verfügbar.

Listen Sie Abonnements auf, für 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 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 AbortController- und AbortSignal-Klassen 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.

• Um die Protokollierung zur Laufzeit zu aktivieren, verwenden Sie das @azure/Logger-Paket :

  import { setLogLevel } from "@azure/logger";
  
  setLogLevel("info");
  

Bündelung

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

• Bündeln der Azure SDKs
• Beispiele für die Bündelung

Nächste Schritte

• Auflisten von Abonnements mit @azure/arm-subscriptions SDK
• Aktuelle Ressourcenvorgänge mit @azure/arm-monitor SDK auflisten
• Erstellen eines virtuellen Computers mit @azure/arm-compute SDK