Usar bibliotecas cliente de Azure para JavaScript yd TypeScript

Para acceder mediante programación a los servicios de Azure, use bibliotecas cliente de Azure para JavaScript. Normalmente, estas bibliotecas pertenecen al paquete npm @azure publicado por azure-sdk.

Diferencias entre bibliotecas cliente y API REST

Consulte la siguiente información para saber cuándo usar cada tipo de acceso.

• Las bibliotecas clientes de Azure es el método preferido para acceder al servicio de Azure. Estas bibliotecas abstraen 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 en los que las bibliotecas cliente de Azure no están disponibles. Piense que el código está su versión preliminar, que debe actualizarse cuando el servicio esté disponible con carácter general con las bibliotecas clientes.
  • 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 las bibliotecas cliente de Azure están disponibles en las siguientes categorías:

• Administración: las bibliotecas de administración permiten crear y administrar recursos de Azure. Puede reconocer estas bibliotecas por el elemento arm- de sus nombres de paquete. El término ARM hace referencia al Azure Resource Manager.
  • Documentación y ejemplos de código
• Cliente: si ya existe un recurso de Azure, use 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

Las bibliotecas cliente de Azure están disponibles gratuitamente en NPM. Instale los SDK que sean necesarios. Cada SDK proporciona definiciones de TypeScript.

Cuando se usa un cliente o un explorador, es necesario agregar bibliotecas cliente de Azure al proceso de agrupació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

Las bibliotecas cliente de Azure necesitan credenciales para autenticarse en la plataforma de Azure. Las clases de credenciales proporcionadas por @azure/identity tienen 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.
• Autenticación encadenada para que haya 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. El cliente puede necesitar información adicional, como un identificador de suscripción o un punto de conexión de servicio. Estos valores están disponibles en Azure Portal para el recurso.

En el ejemplo de código siguiente se usa DefaultAzureCredential y la biblioteca cliente de suscripciones arm para ver las suscripciones a las que tiene acceso de lectura esta credencial.

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

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:

• Iteradores asincrónicos en Azure SDK para JavaScript y TypeScript

Operaciones de larga duración

Un método del SDK puede devolver la respuesta sin procesar 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 una LRO con .pollUntildone() 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:

• @azure/core-lro

Cancelación de operaciones asincrónicas

El paquete @azure/abort-controller incluye 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:

• Uso de señales de anulación para cancelar operaciones en Azure SDK para JavaScript y TypeScript

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 la variable de entorno AZURE_LOG_LEVEL en info.

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

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

Unión

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

• Para la unión de Azure SDK
• Ejemplos de unión

Pasos siguientes

• Ver las suscripciones con el SDK @azure/arm-subscriptions
• Ver las operaciones de recursos recientes con el SDK @azure/arm-monitor