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 terme arm indique Azure Resource Manager.
  • documentation et exemples de code
• 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 :

• itérateurs asynchrones dans le Kit de développement logiciel (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, 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 :

• @azure/core-lro

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:

• Comment utiliser des signaux d’abandon pour annuler des opérations dans le Kit de développement logiciel (SDK) Azure pour JavaScript/TypeScript

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

Étapes suivantes

• Répertorier les abonnements avec le SDK @azure/arm-subscriptions
• Répertorier les opérations de ressource récente avec le SDK @azure/arm-monitor