Utilisation de bibliothèques de client Azure pour JavaScript et TypeScript

Article
09/03/2024

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.

Différences entre les bibliothèques de client et les API REST

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.

Bibliothèques de client et de gestion Azure

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.
- Documentation et exemples de code
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.

Installer les packages npm Azure

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.

Utiliser un exemple de code de package npm Azure

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.

Fournir des informations d’authentification

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.

Créer un client SDK et appeler des méthodes

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);
  });

Pagination asynchrone des résultats

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 :

Itérateurs asynchrones dans le SDK Azure pour JavaScript/TypeScript

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 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 :

@azure/core-lro

Annulation des opérations asynchrones

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 :

Comment utiliser des signaux d’abandon pour annuler des opérations dans le kit SDK Azure pour JavaScript/TypeScript

Journalisation détaillée du SDK

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");
```

Regroupement

Découvrez le regroupement avec le SDK Azure :

Partager via