Uso de Azure SDK para JavaScript y TypeScript

  • Artículo
  • Tiempo de lectura: 5 minutos

Para acceder mediante programación a los servicios de Azure, use los SDK de Azure para JavaScript. Normalmente, estos SDK se incluyen en el ámbito del @azure de paquete npm publicado por azure-sdk.

Diferencias entre los SDK y las API REST

Use la tabla siguiente para saber cuándo usar cada tipo de mecanismo de acceso.

Azure SDK (recomendado) API REST de Azure
Azure SDK es el método preferido para acceder al servicio de Azure. Azure SDK abstrae el código reutilizable necesario para administrar las solicitudes REST de la plataforma de Azure basadas en la nube, como la autenticación, los reintentos y el registro. Las API REST de Azure son el método preferido si va a:
  • Trabajar con servicios en versión preliminar para los que Azure SDK no está disponible. Considere el código como en versión preliminar, que debe actualizarse cuando el servicio esté disponible con carácter general con los SDK.
  • Quiere realizar llamadas REST directamente porque no quiere que todo el SDK use una única API REST o quiere un control más profundo sobre las solicitudes HTTP.

Bibliotecas de cliente y de administración de Azure

Las versiones de Azure SDK están disponibles como:

  • SDK de administración: las bibliotecas de administración permiten aprovisionar y administrar recursos de Azure mediante Azure Resource Manager (ARM). Puede reconocer estas bibliotecas por el elemento @azure/arm- de sus nombres de paquete.
  • SDK de cliente: dado que ya existe un recurso de Azure, usaría las bibliotecas cliente para consumirlo e interactuar con él.
    • Cada archivo README.md de los paquetes incluye documentación y ejemplos.

Instalación de los paquetes npm de Azure

Los diferentes Azure SDK están disponibles de forma gratuita en NPM. Instale los SDK individuales necesarios. Cada SDK proporciona definiciones de TypeScript.

Para el uso de un cliente o un explorador, es necesario agregar Azure SDK al proceso de unión.

Uso del código de ejemplo del paquete npm de Azure

Cada paquete incluye documentación para empezar a trabajar rápidamente con él. Consulte los paquetes NPM específicos que va a utilizar para aprender a usarlos.

Proporcionar credenciales de autenticación

Los distintos Azure SDK requieren credenciales para autenticarse en la plataforma de Azure. Las clases de credenciales proporcionadas por @azure/identity proporcionan varias ventajas:

  • Incorporación rápida
  • Método más seguro
  • Separación del mecanismo de autenticación del código. Esto le permite usar el mismo código localmente y en la plataforma de Azure, aunque las credenciales sean diferentes.
  • Proporcionar autenticación encadenada para que puedan estar disponibles varios mecanismos

Creación de un cliente del SDK y llamada a métodos

Una vez que cree una credencial mediante programación, pase la credencial al cliente de Azure SDK. El cliente puede requerir información adicional, como un identificador de suscripción o una dirección URL de servicio. Estos valores están disponibles en Azure Portal para el recurso.

Enumere las suscripciones a las que esta credencial tiene acceso de lectura.

const { ClientSecretCredential, DefaultAzureCredential } = require("@azure/identity");
const { SubscriptionClient } = require("@azure/arm-subscriptions");

let credentials = null;

const tenantId = process.env["AZURE_TENANT_ID"] || "REPLACE-WITH-YOUR-TENANT-ID"; 
const clientId = process.env["AZURE_CLIENT_ID"] || "REPLACE-WITH-YOUR-CLIENT-ID"; 
const secret = process.env["AZURE_CLIENT_SECRET"] || "REPLACE-WITH-YOUR-CLIENT-SECRET";


if(process.env.production){

  // production
  credentials = new DefaultAzureCredential();

}else{

  // development
  credentials = new ClientSecretCredential(tenantId, clientId, secret);
  console.log("development");
}

// use credential to authenticate with Azure SDKs
let client = new SubscriptionClient(credentials);

const subscriptions = async() =>{

  // get list of Azure subscriptions
  const listOfSubscriptions = await client.subscriptions.list();
  
  // get details of each subscription
  for (const item of listOfSubscriptions) {
  
      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)
  }
}

subscriptions()
.then(()=>console.log("done"))
.catch(ex=>console.log(ex))

Paginación asincrónica de resultados

Un método del SDK puede devolver un iterador asincrónico, PagedAsyncIterableIterator, para permitir resultados asincrónicos. Los resultados pueden usar tokens de paginación y de continuación para dividir los conjuntos de resultados.

En el siguiente ejemplo de JavaScript, se muestra la paginación asincrónica. El código establece un tamaño de paginación artificialmente corto de 2 para mostrar de forma rápida y visual el proceso al ejecutar el código de ejemplo en la depuración.

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

Más información sobre la paginación y los iteradores en Azure:

Operaciones de larga duración

Un método del SDK puede devolver una respuesta de una operación de larga duración (LRO). Esta respuesta contiene información que incluye:

  • La solicitud se ha completado.
  • La solicitud todavía está en proceso.

En el siguiente ejemplo de JavaScript se muestra cómo esperar a que se complete un LRO, con , antes de continuar.

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

Más información sobre las operaciones de larga duración en Azure:

Cancelación de operaciones asincrónicas

El @azure/abort-controller proporciona las clases AbortController y AbortSignal. Use AbortController para crear un elemento AbortSignal, que luego se puede pasar a las operaciones de Azure SDK para cancelar el trabajo pendiente. Las operaciones de Azure SDK pueden ser:

  • Anulado en función de su propia lógica
  • Anulado en función de un límite de tiempo de espera
  • Anulado en función de una señal de la tarea primaria
  • Anulado en función de una señal de la tarea primaria o un límite de tiempo de espera

Más información:

Registro detallado desde el SDK

Al usar Azure SDK, puede haber ocasiones en las que necesite depurar la aplicación.

  • Para habilitar el registro en tiempo de compilación,establezca AZURE_LOG_LEVEL variable de entorno en .

  • Para habilitar el registro en tiempo de ejecución,use el @azure/registrador:

    import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Unión

Obtenga información sobre la unión con Azure SDK:

Pasos siguientes