Utilisation de bibliothèques de client Azure pour JavaScript et TypeScript
Pour accéder programmatiquement à vos services Azure, utilisez les bibliothèques de client Azure pour JavaScript. En règle générale, ces bibliothèques sont délimités à l’étendue du package npm @azure publiée par azure-sdk.
Utilisez les informations suivantes pour comprendre quand utiliser quel type d’accès.
- Les bibliothèques de client Azure sont la méthode recommandée pour accéder à votre service Azure. Ces bibliothèques éliminent le code réutilisable nécessaire pour gérer les demandes REST de la plateforme Azure basées sur le Cloud, telles que l’authentification, les nouvelles tentatives et la journalisation.
- Les API REST Azure sont la méthode recommandée si vous :
- Travaillez avec des services en préversion qui n’ont pas de bibliothèques de client Azure disponible. Considérez votre code comme une préversion qui devra être mise à jour lorsque le service passera en disponibilité générale avec les bibliothèques de client.
- Souhaitez effectuer des appels REST directement parce que vous ne voulez pas que le kit SDK entier utilise une seule API REST ou parce que vous voulez un contrôle plus poussé sur les requêtes HTTP.
Les versions de bibliothèque de client Azure sont disponibles sous les formes suivantes :
- Gestion : les bibliothèques de gestion vous permettent de créer et de gérer des ressources Azure. Vous pouvez reconnaître ces bibliothèques avec
arm-
dans leur nom de package. Le terme ARM se réfère à Azure Resource Manager. - Client : si une ressource Azure existe déjà, vous utilisez normalement les bibliothèques de client pour la consommer et interagir avec.
- Chaque package README.md comprend une documentation et des exemples.
Les bibliothèques de client Azure sont disponibles gratuitement via NPM. Installez les kits SDK si besoin. Chaque SDK fournit des définitions TypeScript.
Pour les utiliser avec un client/navigateur, les bibliothèques de client Azure doivent être ajoutés à votre processus de regroupement.
Chaque package comprend une documentation qui vous aidera à commencer à utiliser rapidement le package. Reportez-vous aux packages NPM spécifiques que vous utilisez pour apprendre à les utiliser.
Les bibliothèques de client Azure demandent des informations d’identification pour s’authentifier auprès de la plateforme Azure. Les classes d’informations d’identification fournies par @azure/identity offrent plusieurs avantages :
- Intégration rapide
- Méthode la plus sécurisée
- Séparez le mécanisme d’authentification du code. Cela vous permet d’utiliser le même code en local et sur la plateforme Azure, alors que les informations d’identification sont différentes.
- Fournir une authentification chaînée pour avoir plusieurs mécanismes disponibles.
Une fois que vous avez créé des informations d’identification programmatiquement, transmettez les informations d’identification à votre client Azure. Le client peut demander des informations supplémentaires, telles qu’un ID d’abonnement ou un point de terminaison de service. Ces valeurs sont disponibles dans le portail Azure, pour votre ressource.
L’exemple de code suivant utilise DefaultAzureCredential et la bibliothèque de client d’abonnement arm
pour répertorier les abonnements auxquels ces informations d’identification ont accès en lecture.
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);
});
Une méthode de SDK peut retourner un itérateur asynchrone, PagedAsyncIterableIterator, pour autoriser des résultats asynchrones. Les résultats peuvent utiliser des jetons de pagination et de continuation pour décomposer les jeux de résultats.
L’exemple JavaScript suivant illustre la pagination asynchrone. Le code définit une taille de pagination artificiellement petite de 2 afin d’avoir un aperçu rapide et visuel du processus lorsque vous exécutez l’exemple de code en débogage.
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)
);
En savoir plus sur la pagination et les itérateurs sur Azure :
Une méthode de SDK peut retourner une réponse brute d’opération de longue durée (LRO). Cette réponse inclut des informations telles que :
- Votre demande terminée
- Votre demande toujours en cours
L’exemple JavaScript suivant montre comment attendre la fin d’une opération de longue durée, avec .pollUntildone()
, avant de poursuivre.
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)
);
En savoir plus sur les opérations de longue durée sur Azure :
Le package @azure/abort-controller fournit les classes AbortController et AbortSignal. Utilisez AbortController pour créer un AbortSignal, qui peut ensuite être passé aux opérations du kit SDK Azure pour annuler le travail en attente. Les opérations de SDK Azure peuvent être :
- Abandonnées en fonction de votre propre logique
- Abandonnées en fonction d’un délai d’expiration
- Abandonnées en fonction d’un signal d’une tâche parente
- Abandonnées en fonction d’un signal d’une tâche parente ou d’un délai d’expiration
En savoir plus :
Lorsque vous utilisez un SDK Azure, vous aurez parfois peut-être besoin de déboguer votre application.
Pour activer la journalisation au moment de la génération, affectez la valeur
info
à la variable d’environnement AZURE_LOG_LEVEL.Pour activer la journalisation au moment de l’exécution, utilisez le package @azure/logger :
import { setLogLevel } from "@azure/logger"; setLogLevel("info");
Découvrez le regroupement avec le SDK Azure :