Usare Gli SDK di Azure per JavaScript e TypeScript

Per accedere ai servizi di Azure a livello di codice, usare gli SDK di Azure per JavaScript. In genere, questi SDK hanno come ambito l'ambito del pacchetto npm @azure pubblicato da azure-sdk.

Differenze tra SDK e API REST

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

• Gli SDK di Azure sono il metodo preferito per accedere al servizio di Azure. Gli SDK di Azure astraggono 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 AZURE SDK disponibili. Prendere in considerazione il codice come anteprima, che deve essere aggiornato quando il servizio è disponibile a livello generale con gli SDK.
  • 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 di Azure SDK sono disponibili come:

• SDK di gestione: le librerie di gestione consentono di effettuare il provisioning e gestire le risorse di Azure tramite Azure Resource Manager (ARM). È possibile riconoscere queste librerie @azure/arm- in base ai nomi dei pacchetti.
  • Documentazione ed esempi di codice
• SDK client: dato che esiste già una risorsa di Azure, è possibile usare le librerie client per usarlo e interagire con esso.
  • Ogni pacchetto README.md include documentazione ed esempi.

Installare pacchetti npm di Azure

Gli SDK di Azure sono disponibili gratuitamente da NPM. Installare singoli SDK necessari. Ogni SDK fornisce definizioni TypeScript.

Per l'utilizzo di client/browser, gli SDK di Azure devono essere aggiunti 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

Gli SDK di Azure richiedono credenziali per l'autenticazione alla 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 diversi meccanismi possano essere disponibili

Creare un client SDK e chiamare i metodi

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

Elencare le sottoscrizioni a cui le credenziali hanno 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 LRO (Long Running Operation). 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
• Creare una macchina virtuale con @azure/arm-compute SDK