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 hanno come ambito l'ambito del pacchetto npm @azure pubblicato da azure-sdk.

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.
• Le API REST di Azure sono il metodo preferito se si è:
  • Uso dei servizi di anteprima che non dispongono di librerie client di Azure disponibili. Prendere in considerazione il codice come anteprima, che deve essere aggiornato quando il servizio è disponibile a livello generale 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

Le versioni della libreria client di Azure sono disponibili come segue:

• Gestione: le librerie di gestione consentono di creare e gestire le risorse di Azure. È possibile riconoscere queste librerie arm- in base ai nomi dei pacchetti. 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 usarla e interagire con essa.
  • Ogni pacchetto README.md include documentazione ed esempi.

Installare pacchetti npm di Azure

Le librerie client di Azure sono disponibili gratuitamente da Monitoraggio prestazioni rete. Installare singoli SDK in base alle esigenze. Ogni SDK fornisce definizioni TypeScript.

Per l'utilizzo di client/browser, le librerie client di Azure devono essere aggiunte al processo di creazione di bundle.

Usare il codice di esempio del pacchetto npm di Azure

Ogni pacchetto include la documentazione per iniziare rapidamente a usare il pacchetto. Per informazioni su come usarli, vedere i pacchetti NPM specifici usati.

Specificare le credenziali di autenticazione

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

• Onboarding rapido
• 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 nella portale di Azure per la risorsa.

L'esempio di codice seguente usa DefaultAzureCredential e la arm libreria client di sottoscrizione 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);
  });

Paging asincrono dei risultati

Un metodo SDK può restituire un iteratore asincrono, PagedAsyncIterableIterator, 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 in Azure SDK per JavaScript/TypeScript

Operazioni a esecuzione prolungata

Un metodo SDK può restituire una risposta non elaborata con esecuzione prolungata. Questa risposta include informazioni tra cui:

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

L'esempio JavaScript seguente illustra 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 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 propria logica
• Interrotto in base a un limite di timeout
• Interrotto in base al segnale di un'attività padre
• Interrotto in base al segnale di un'attività padre o a un limite di timeout

Altre informazioni:

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

Registrazione dettagliata dall'SDK

Quando si usa Azure SDK, può verificarsi un momento 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");
  

Impacchettare

Informazioni sulla creazione di bundle con Azure SDK:

• Per aggregare gli SDK di Azure
• Esempi di creazione di bundle

Passaggi successivi

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