Använda Azure-klientbibliotek för JavaScript och TypeScript

Om du vill komma åt dina Azure-tjänster programmatiskt använder du Azure-klientbiblioteken för JavaScript. Vanligtvis är dessa bibliotek begränsade inom npm-omfånget @azure som publicerats av microsoft1es.

Skillnader mellan klientbibliotek och REST-API:er

Använd följande information för att förstå när du ska använda vilken typ av åtkomst.

• Azure-klientbibliotek är den bästa metoden för att komma åt din Azure-tjänst. Dessa bibliotek abstraherar bort den exempelkod som krävs för att hantera molnbaserade REST-begäranden för Azure-plattformen, till exempel autentisering, återförsök och loggning.
• Azure REST API:er är den bästa metoden om du är:
  • Arbeta med förhandsversionstjänster som inte har tillgängliga Azure-klientbibliotek. Tänk på din kod som förhandsversion, som bör uppdateras när tjänsten är allmänt tillgänglig med klientbibliotek.
  • Vill du göra REST-anrop direkt eftersom du inte vill att hela SDK:n ska använda ett enda REST-API eller om du vill ha djupare kontroll över HTTP-begäranden.

Azure-klient- och hanteringsbibliotek

Azure-klientbiblioteket versioner är tillgängliga som:

• Management: Med hanteringsbibliotek kan du skapa och hantera Azure-resurser. Du kan känna igen dessa bibliotek på att arm- förekommer i deras paketnamn. Termen arm avser Azure Resource Manager.
  • Dokumentation och kodexempel
• Client: Eftersom det redan finns en Azure-resurs använder du klientbiblioteken för att använda den och interagera med den.
  • Varje paket README.md innehåller dokumentation och exempel.

Installera Azure npm-paket

Azure-klientbibliotek är fritt tillgängliga från NPM och Yarn. Installera enskilda SDK:er efter behov. Varje SDK innehåller TypeScript-definitioner.

För att använda klient-/webbläsaren måste du lägga till Azure-klientbibliotek i din -buntningsprocess.

Använda Azure npm-paketexempelkod

Varje paket innehåller dokumentation för att snabbt komma igång med paketet. Se dokumentationen för det specifika paketet som du använder för att lära dig hur du använder dem.

Ange autentiseringsuppgifter

Azure-klientbiblioteken kräver autentiseringsuppgifter för att autentisera till Azure-plattformen. referensklasser som tillhandahålls av @azure/identity ger flera fördelar:

• Snabb registrering
• Säkraste metoden
• Separera autentiseringsmekanismen från koden. På så sätt kan du använda samma kod lokalt och på Azure-plattformen medan autentiseringsuppgifterna skiljer sig åt.
• Tillhandahåll länkad autentisering så att flera mekanismer kan vara tillgängliga.

Skapa en SDK-klient och anropsmetoder

När du har skapat en autentiseringsuppgift programmatiskt skickar du autentiseringsuppgifterna till Din Azure-klient. Klienten kan kräva ytterligare information, till exempel ett prenumerations-ID eller en tjänstslutpunkt. Dessa värden är tillgängliga i Azure-portalen för din resurs.

I följande kodexempel används StandardAzureCredential och klientbiblioteket för arm-prenumeration för att visa prenumerationer som den här autentiseringsuppgiften har åtkomst till att läsa.

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

Asynkron paginering av resultat

En SDK-metod kan returnera en asynkron iterator, PagedAsyncIterableIterator, för att tillåta asynkrona resultat. Resultaten kan använda sig av paginering och fortsättningstoken för att dela upp resultatuppsättningar.

Följande JavaScript-exempel visar asynkron sidindelning. Koden ställer in en konstlat kort sidstorlek på 2 för att snabbt och visuellt demonstrera processen när du kör exempelkoden under felsökning.

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

Läs mer om paginering och iteratorer i Azure.

• sv-SE: Async Iterators i Azure SDK för JavaScript/TypeScript

Tidskrävande åtgärder

En SDK-metod kan returnera en tidskrävande åtgärd (LRO) råsvar. Det här svaret innehåller information som:

• Din begäran har slutförts
• Din begäran pågår fortfarande

Följande JavaScript-exempel visar hur du väntar på att en LRO ska slutföras, med .pollUntildone(), innan du fortsätter.

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

Läs mer om tidskrävande åtgärder i Azure:

• @azure/core-lro

Avbryta asynkrona åtgärder

Paketet @azure/abort-controller innehåller klasser för AbortController och AbortSignal. Använd AbortController för att skapa en AbortSignal, som sedan kan skickas till Azure SDK-åtgärder för att avbryta väntande arbete. Azure SDK-åtgärder kan vara:

• Avbröts baserat på din egen logik
• Avbröts på grund av en tidsgräns
• Avbröts baserat på en överordnad uppgiftssignal
• Avbröts baserat på en överordnad uppgifts signal eller och en tidsgräns

Lära sig mer:

• Så här använder du abortsignaler för att avbryta åtgärder i Azure SDK för JavaScript/TypeScript

Utförlig loggning från SDK:et

När du använder Azure SDK kan det finnas tillfällen då du behöver felsöka ditt program.

• Om du vill aktivera loggning vid byggtidanger du AZURE_LOG_LEVEL miljövariabeln till info.

• Om du vill aktivera loggning vid körninganvänder du @azure/logger--paketet:

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

Kombinationserbjudanden

Lär dig mer om paketering med Azure SDK:

• Så här paketar du Azure SDK:er
• Samling av prover

Nästa steg

• Lista prenumerationer med @azure/arm-prenumerationer SDK
• Lista de senaste resursåtgärderna med @azure/arm-monitor SDK