Azure-SDK's gebruiken voor JavaScript en TypeScript

  • Artikel

Gebruik de Azure SDK's voor JavaScript om programmatisch toegang te krijgen tot uw Azure-services. Deze SDK's hebben doorgaans het bereik van het @azure npm-pakketbereik dat is gepubliceerd door azure-sdk.

Verschillen tussen SDK's en REST API's

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

  • De Azure SDK's zijn de voorkeursmethode voor toegang tot uw Azure-service. De Azure SDK's abstraheren de standaardcode die is vereist voor het beheren van azure-platform-REST-aanvragen in de cloud, zoals verificatie, nieuwe pogingen en logboekregistratie.
  • Azure REST API's zijn de voorkeursmethode als u:
    • Werken met preview-services waarvoor geen Azure SDK's beschikbaar zijn. Houd rekening met uw code als preview, die moet worden bijgewerkt wanneer de service algemeen beschikbaar is met SDK's.
    • 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 SDK-releases zijn beschikbaar als:

  • Beheer-SDK's: met beheerbibliotheken kunt u Azure-resources inrichten en beheren via arm (Azure Resource Manager). U kunt deze bibliotheken herkennen @azure/arm- op basis van hun pakketnamen.
  • Client-SDK's: 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 SDK's zijn vrij beschikbaar via NPM. Installeer afzonderlijke SDK's die nodig zijn. Elke SDK biedt TypeScript-definities.

Voor client-/browsergebruik moeten Azure SDK's 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 SDK's zijn referenties vereist voor verificatie 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.
  • Ketenverificatie bieden, 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 de client van uw Azure SDK. De client vereist mogelijk aanvullende informatie, zoals een abonnements-id of service-URL. Deze waarden zijn beschikbaar in Azure Portal voor uw resource.

Geef abonnementen weer 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:

Langlopende bewerkingen

Een SDK-methode kan een LRO-antwoord (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:

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:

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:

Volgende stappen