Usare le librerie client di Azure per JavaScript e TypeScript

Per accedere ai servizi di Azure a livello di codice, usare le librerie client di Azure per JavaScript. In genere, queste librerie sono incluse nell'ambito del pacchetto npm @azure, pubblicato da microsoft1es.

Differenze tra librerie client e API REST

Usare le informazioni seguenti per comprendere quando usare il tipo di accesso.

• Le librerie client di Azure sono il metodo preferito per accedere al servizio di Azure. Queste librerie estraggono il codice boilerplate necessario per gestire le richieste REST della piattaforma Azure basate sul cloud, ad esempio l'autenticazione, i tentativi e la registrazione.
• api REST di Azure sono il metodo preferito se si è:
  • Uso dei servizi di anteprima che non dispongono di librerie client di Azure disponibili. Considera il tuo codice come un'anteprima, che dovrebbe essere aggiornato quando il servizio è generalmente disponibile con le librerie client.
  • Si vuole effettuare chiamate REST direttamente perché non si vuole che l'intero SDK usi una singola API REST o si voglia un controllo più approfondito sulle richieste HTTP.

Librerie client e di gestione di Azure

La libreria client di Azure versioni sono disponibili come segue:

• Management: le librerie di gestione consentono di creare e gestire le risorse di Azure. È possibile riconoscere queste librerie con arm- nei loro nomi di pacchetto. Il termine arm indica Azure Resource Manager.
  • documentazione ed esempi di codice
• Client: dato che esiste già una risorsa di Azure, usare le librerie client per usarlo e interagire con esso.
  • Ogni pacchetto README.md include documentazione ed esempi.

Installare pacchetti npm di Azure

Le librerie client di Azure sono disponibili gratuitamente da NPM e Yarn. Installare singoli SDK in base alle esigenze. Ogni SDK fornisce definizioni TypeScript.

Per l'utilizzo del client o del browser, è necessario aggiungere le librerie client di Azure al tuo processo di bundling .

Usare il codice di esempio del pacchetto npm di Azure

Ogni pacchetto include la documentazione per iniziare rapidamente a usare il pacchetto. Fare riferimento alla documentazione del pacchetto specifica usata per informazioni su come usarle.

Specificare le credenziali di autenticazione

Le librerie client di Azure richiedono credenziali per l'autenticazione alla piattaforma Azure. classi di credenziali fornite da @azure/identity offrono diversi vantaggi:

• Rapido onboarding
• Metodo più sicuro
• Separare il meccanismo di autenticazione dal codice. In questo modo è possibile usare lo stesso codice in locale e nella piattaforma Azure, mentre le credenziali sono diverse.
• Fornire l'autenticazione concatenata in modo che siano disponibili diversi meccanismi.

Creare un client SDK e chiamare i metodi

Dopo aver creato una credenziale a livello di codice, passare le credenziali al client di Azure. Il client può richiedere informazioni aggiuntive, ad esempio un ID sottoscrizione o un endpoint di servizio. Questi valori sono disponibili nel portale di Azure per la risorsa.

L'esempio di codice seguente usa DefaultAzureCredential e la libreria client di sottoscrizione arm per elencare le sottoscrizioni a cui questa credenziale ha accesso per la lettura.

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

Asincrona paginazione dei risultati

Un metodo SDK può restituire un iteratore asincrono, PagedAsyncIterator, per consentire risultati asincroni. I risultati possono usare il paging e i token di continuazione per suddividere i set di risultati.

L'esempio javaScript seguente illustra il paging asincrono. Il codice imposta una dimensione di paging artificialmente breve pari a 2 per illustrare in modo rapido e visivo il processo quando si esegue il codice di esempio nel debug.

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

Altre informazioni sul paging e sugli iteratori in Azure:

• Iteratori Asincroni nell'Azure SDK per JavaScript/TypeScript

Operazioni a esecuzione prolungata

Un metodo SDK può restituire un'operazione a esecuzione prolungata (LRO) risposta non elaborata. Questa risposta include informazioni tra cui:

• La richiesta è stata completata
• La richiesta è ancora in corso

Nell'esempio JavaScript seguente viene illustrato come attendere il completamento di un LRO, con .pollUntildone(), prima di continuare.

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

Altre informazioni sulle operazioni a esecuzione prolungata in Azure:

• @azure/core-lro

Annullamento di operazioni asincrone

Il pacchetto @azure/abort-controller fornisce le classi AbortController e AbortSignal. Usare AbortController per creare un oggetto AbortSignal, che può quindi essere passato alle operazioni di Azure SDK per annullare il lavoro in sospeso. Le operazioni di Azure SDK possono essere:

• Interrotto in base alla tua logica
• Interrotto per superamento del limite di tempo
• Interrotto in base al segnale di un compito padre
• Interrotto in base al segnale di un'attività principale o a causa di un limite di timeout.

Ulteriori informazioni:

• Come usare i segnali di interruzione per annullare le operazioni in Azure SDK per JavaScript/TypeScript

Registrazione dettagliata proveniente dall'SDK

Quando si usa Azure SDK, possono verificarsi momenti in cui è necessario eseguire il debug dell'applicazione.

• Per abilitare la registrazione in fase di compilazione , impostare la variabile di ambiente AZURE_LOG_LEVEL su info.

• Per abilitare la registrazione in fase di esecuzione , usare il pacchetto @azure/logger:

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

Aggregazione

Informazioni sulla creazione di bundle con Azure SDK:

• Per aggregare gli SDK di Azure
• Esempi di raggruppamento

Passaggi successivi

• Elencare le sottoscrizioni con @azure/arm-subscriptions SDK
• Elenca le operazioni recenti delle risorse con @azure/arm-monitor SDK