Utiliser des bibliothèques clientes Azure pour JavaScript et TypeScript
Pour accéder par programmation à vos services Azure, utilisez les bibliothèques clientes 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 microsoft1es.
Différences entre les bibliothèques clientes et les API REST
Utilisez les informations suivantes pour comprendre quand utiliser le 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 requis pour gérer les demandes REST de plateforme Azure basées sur le cloud, telles que l’authentification, les nouvelles tentatives et la journalisation.
- API REST Azure sont la méthode par défaut si vous êtes :
- Utilisation des services en préversion qui n’ont pas de bibliothèques clientes Azure disponibles. Considérez votre code en préversion, qui doit être mis à jour lorsque le service est généralement disponible avec les bibliothèques clientes.
- Vous souhaitez effectuer des appels REST directement, car vous ne souhaitez pas que l’ensemble du SDK utilise une SEULE API REST ou que vous souhaitez un contrôle plus approfondi sur les requêtes HTTP.
Bibliothèques de client et de gestion Azure
Les versions de la bibliothèque cliente Azure sont disponibles comme suit :
- Management: les bibliothèques de gestion vous permettent de créer et de gérer des ressources Azure. Vous pouvez reconnaître ces bibliothèques en
arm-
dans leurs noms de package. Le termearm
indique Azure Resource Manager. - client: étant donné qu’une ressource Azure existe déjà, utilisez les bibliothèques clientes pour l’utiliser et interagir avec elle.
- Chaque package README.md inclut la documentation et les exemples.
Installer des packages Azure npm
Les bibliothèques clientes Azure sont disponibles gratuitement à partir de NPM et Yarn. Installez des kits SDK individuels en fonction des besoins. Chaque SDK fournit des définitions TypeScript.
Pour l’utilisation du client/du navigateur, les bibliothèques clientes Azure doivent être ajoutées à votre processus de regroupement .
Utiliser un exemple de code de package Azure npm
Chaque package inclut la documentation pour vous aider rapidement à démarrer le package. Reportez-vous à la documentation du package spécifique que vous utilisez pour apprendre à les utiliser.
Fournir des informations d’authentification
Les bibliothèques clientes Azure nécessitent 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 localement et sur la plateforme Azure, tandis que les informations d’identification sont différentes.
- Fournissez l’authentification chaînée afin que plusieurs mécanismes puissent être disponibles.
Créer un client sdk et appeler des méthodes
Une fois que vous avez créé des informations d’identification par programme, transmettez les informations d’identification à votre client Azure. Le client peut nécessiter 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 cliente d’abonnement arm
pour répertorier les abonnements auxquels ces informations d’identification ont accès à la 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);
});
Pagination asynchrone des résultats
Une méthode sdk peut retourner un itérateur asynchrone, PagedAsyncIterableIterator, pour permettre des résultats asynchrones. Les résultats peuvent utiliser des jetons de pagination et de continuation pour segmenter les ensembles de résultats.
L’exemple javaScript suivant illustre la pagination asynchrone. Le code définit une taille de pagination artificiellement courte de 2 afin de montrer rapidement et visuellement le processus lorsque vous exécutez l’exemple de code dans le 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 :
Opérations de longue durée
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, notamment :
- Votre demande a été complétée
- Votre demande est toujours en cours de traitement
L’exemple javaScript suivant montre comment attendre la fin d’un LRO, avec .pollUntildone()
, avant de continuer.
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 :
Annulation d’opérations asynchrones
Le package @azure/abort-controller fournit les classes AbortController et AbortSignal. Utilisez AbortController pour créer un AbortSignal, qui peut être ensuite passé aux opérations du SDK Azure pour annuler les tâches en cours. Les opérations du Kit de développement logiciel (SDK) Azure peuvent être les suivantes :
- 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
Pour en savoir plus:
Journalisation détaillée du SDK
Lorsque vous utilisez le Kit de développement logiciel (SDK) Azure, il peut arriver que vous deviez 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");
Regroupement
En savoir plus sur le regroupement avec le Kit de développement logiciel (SDK) Azure :
- pour regrouper les kits de développement logiciel (SDK) Azure
- exemples de regroupement