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 terminearm
indica Azure Resource Manager. -
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:
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:
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:
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: