Azure-clientbibliotheken gebruiken voor JavaScript en TypeScript

2025-03-09

Als u programmatisch toegang wilt krijgen tot uw Azure-services, gebruikt u de Azure-clientbibliotheken voor JavaScript. Deze bibliotheken zijn doorgaans afgestemd op het @azure npm-pakketbereik dat is gepubliceerd door microsoft1es.

Verschillen tussen clientbibliotheken en REST API's

Gebruik de volgende informatie om te begrijpen wanneer u welk type toegang moet gebruiken.

De Azure-clientbibliotheken zijn de voorkeursmethode voor toegang tot uw Azure-service. Deze bibliotheken abstraheren de standaardcode die nodig is voor het beheren van CLOUDgebaseerde Azure-platform REST-aanvragen, zoals verificatie, nieuwe pogingen en logboekregistratie.
Azure REST API's de voorkeursmethode zijn als u:
- Werken met preview-services waarvoor geen Azure-clientbibliotheken beschikbaar zijn. Houd rekening met uw code als preview, die moet worden bijgewerkt wanneer de service algemeen beschikbaar is met clientbibliotheken.
- U wilt REST-aanroepen rechtstreeks uitvoeren omdat u niet wilt dat de hele SDK één REST API gebruikt of als u meer controle wilt over de HTTP-aanvragen.

Azure-client- en beheerbibliotheken

De Azure-clientbibliotheek releases beschikbaar zijn als:

Management: met beheerbibliotheken kunt u Azure-resources maken en beheren. U kunt deze bibliotheken herkennen door arm- in hun pakketnamen. De term arm geeft de Azure Resource Manager aan.
- documentatie en codevoorbeelden
Client-: Als er al een Azure-resource bestaat, gebruikt u de clientbibliotheken om deze te gebruiken en ermee te communiceren.
- Elk pakket README.md bevat documentatie en voorbeelden.

Azure npm-pakketten installeren

Azure-clientbibliotheken zijn vrij beschikbaar via NPM en Yarn. Installeer indien nodig afzonderlijke SDK's. Elke SDK biedt TypeScript-definities.

Voor client-/browsergebruik moeten Azure-clientbibliotheken worden toegevoegd aan uw bundelen proces.

Azure npm-pakketvoorbeeldcode gebruiken

Elk pakket bevat documentatie waarmee u snel aan de slag kunt met het pakket. Raadpleeg de documentatie van het specifieke pakket dat u gebruikt voor meer informatie over het gebruik ervan.

Verificatiereferenties opgeven

De Azure-clientbibliotheken vereisen referenties om te authenticeren bij het Azure-platform. Credential-klassen die worden geleverd door @azure/identity bieden verschillende voordelen:

Snelle onboarding
Veiligste methode
Scheid het verificatiemechanisme van de code. Hierdoor kunt u dezelfde code lokaal en op het Azure-platform gebruiken, terwijl de referenties verschillen.
Voorzien in ketenverificatie, zodat verschillende mechanismen beschikbaar kunnen zijn.

Een SDK-client en -aanroepmethoden maken

Zodra u programmatisch een referentie hebt gemaakt, geeft u de referentie door aan uw Azure-client. De client vereist mogelijk aanvullende informatie, zoals een abonnements-id of service-eindpunt. Deze waarden zijn beschikbaar in Azure Portal voor uw resource.

In het volgende codevoorbeeld worden de DefaultAzureCredential en de clientbibliotheek van het arm-abonnement gebruikt om abonnementen weer te geven waartoe deze referentie toegang heeft.

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);
  });

Asynchrone paginering van resultaten

Een SDK-methode kan een asynchrone iterator, PagedAsyncIterableIterator, retourneren om asynchrone resultaten toe te staan. De resultaten kunnen paging- en vervolgtokens gebruiken om resultatensets op te splitsen.

Het volgende JavaScript-voorbeeld demonstreert asynchrone paging. Met de code wordt een kunstmatig korte paginagrootte van 2 ingesteld om snel en visueel het proces te demonstreren wanneer je de voorbeeldcode in debugmodus uitvoert.

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)
);

Meer informatie over paging en iterators in Azure:

Asynchrone iterators in de Azure SDK voor JavaScript/TypeScript

Langlopende bewerkingen

Een SDK-methode kan een langdurige bewerking (LRO) retourneren ruwe respons. Dit antwoord bevat informatie, waaronder:

Uw aanvraag is voltooid
Uw aanvraag is nog in verwerking

Het volgende JavaScript-voorbeeld laat zien hoe je moet wachten tot een LRO is voltooid voordat je verdergaat, met .pollUntildone().

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)
);

Meer informatie over langdurige bewerkingen in Azure:

@azure/core-lro

Asynchrone bewerkingen annuleren

Het @azure/abort-controller- pakket biedt AbortController- en AbortSignal-klassen. Gebruik de AbortController om een AbortSignal te maken, die vervolgens kan worden doorgegeven aan Azure SDK-bewerkingen om wachtend werk te annuleren. Azure SDK-bewerkingen kunnen het volgende zijn:

Afgebroken op basis van uw eigen logica
Afgebroken vanwege een time-out-limiet
Afgebroken op basis van het signaal van een ouder taak
Afgebroken op basis van het signaal van een bovenliggende taak of of een time-out limiet

Meer informatie:

Abort-signalen gebruiken om bewerkingen te annuleren in de Azure SDK voor JavaScript/TypeScript-

Uitgebreide logboekregistratie van de SDK

Wanneer u de Azure SDK gebruikt, kan het voorkomen dat u fouten in uw toepassing moet opsporen.

Als u logboekregistratie wilt inschakelen op build-time-, stelt u de omgevingsvariabele AZURE_LOG_LEVEL in op info.
Als u logboekregistratie wilt inschakelen op runtime-, gebruikt u het pakket @azure/logger:
```
import { setLogLevel } from "@azure/logger";

setLogLevel("info");
```