Azure-clientbibliotheken gebruiken voor JavaScript en TypeScript

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

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 zijn de voorkeursmethode 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-clientbibliotheekreleases zijn beschikbaar als:

• Beheer: Met beheerbibliotheken kunt u Azure-resources maken en beheren. U kunt deze bibliotheken herkennen arm- op basis van 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. Installeer indien nodig afzonderlijke SDK's. Elke SDK biedt TypeScript-definities.

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

Azure npm-pakketvoorbeeldcode gebruiken

Elk pakket bevat documentatie waarmee u snel aan de slag kunt met het pakket. Raadpleeg de specifieke NPM-pakketten die u gebruikt voor meer informatie over het gebruik ervan.

Verificatiereferenties opgeven

Voor de Azure-clientbibliotheken zijn referenties vereist om te verifiëren bij het Azure-platform. Referentieklassen van @azure/identiteit 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 arm abonnementsclientbibliotheek 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 paging van resultaten

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

In het volgende JavaScript-voorbeeld ziet u asynchrone paging. Met de code wordt een kunstmatig korte paginggrootte van 2 ingesteld om snel en visueel het proces te demonstreren wanneer u de voorbeeldcode uitvoert in foutopsporing.

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 onbewerktE LRO-reactie (Long Running Operation) retourneren. Dit antwoord bevat informatie, waaronder:

• Uw aanvraag is voltooid
• Uw aanvraag is nog in verwerking

In het volgende JavaScript-voorbeeld ziet u hoe u wacht totdat een LRO is voltooid, met .pollUntildone(), voordat u doorgaat.

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 pakket @azure/abort-controller biedt de klassen AbortController en AbortSignal. 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 op basis van een time-outlimiet
• Afgebroken op basis van het signaal van een bovenliggende taak
• Afgebroken op basis van het signaal van een bovenliggende taak of een time-outlimiet

Meer informatie:

• Afgebroken signalen gebruiken om bewerkingen in de Azure SDK voor JavaScript/TypeScript te annuleren

Uitgebreide logboekregistratie van de SDK

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

• Als u logboekregistratie tijdens de build-tijd wilt inschakelen, stelt u de omgevingsvariabele AZURE_LOG_LEVEL in op info.

• Als u logboekregistratie tijdens runtime wilt inschakelen, gebruikt u het pakket @azure/logger :

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

Bundeling

Meer informatie over bundeling met de Azure SDK:

• De Azure SDK's bundelen
• Bundelingsvoorbeelden

Volgende stappen

• Abonnementen weergeven met @azure/arm-subscriptions SDK
• Recente resourcebewerkingen weergeven met @azure/arm-monitor SDK