Utiliser les kits SDK Azure pour JavaScript et TypeScript

Pour accéder programmatiquement à vos services Azure, utilisez les kits SDK Azure pour JavaScript. En règle générale, ces kits SDK sont étendus avec l’étendue du package npm @azure publiée par azure-sdk.

Différences entre les kits SDK et les API REST

Utilisez les informations suivantes pour comprendre quand utiliser le type de mécanisme d’accès.

• Les kits SDK Azure sont la méthode recommandée pour accéder à votre service Azure. Les kits SDK Azure é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 par défaut si vous êtes :
  • Travaillez avec des services en préversion qui n’ont pas de kit SDK 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 kits SDK.
  • 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 publications des kits SDK Azure sont disponibles sous les formes suivantes :

• Kits SDK de gestion : Les bibliothèques de gestion vous permettent de provisionner et de gérer des ressources Azure via Azure Resource Manager (ARM). Vous pouvez reconnaître ces bibliothèques avec @azure/arm- dans leur nom de package.
  • Documentation et exemples de code
• Kits SDK de 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 kits SDK Azure sont disponibles gratuitement sur NPM. Installez les kits SDK dont vous avez besoin. Chaque SDK fournit des définitions TypeScript.

Pour les utiliser avec un client/navigateur, les kits SDK 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 kits SDK 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 au client de votre kit SDK Azure. Le client peut demander des informations supplémentaires, telles qu’un ID d’abonnement ou une URL de service. Ces valeurs sont disponibles dans le portail Azure, pour votre ressource.

Listez 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 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 des 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/enregistreur d’événements :

  import { setLogLevel } from "@azure/logger";
  
  setLogLevel("info");
  

Regroupement

Découvrez le regroupement avec le SDK Azure :

• Pour regrouper les kits SDK Azure
• Exemples de regroupement

Étapes suivantes

• Répertorier les abonnements avec le SDK @azure/arm-subscriptions
• Répertorier les opérations de ressources récentes avec @azure/kit de développement logiciel (SDK) arm-monitor
• Créer une machine virtuelle avec @azure/arm-compute SDK