Uso de bibliotecas cliente de Azure para JavaScript y TypeScript

Para acceder mediante programación a los servicios de Azure, use las bibliotecas cliente de Azure para JavaScript. Normalmente, estas bibliotecas están dentro del ámbito del paquete npm @azure publicado por microsoft1es.

Diferencias entre las bibliotecas cliente y las API REST

Use la siguiente información para comprender cuándo usar el tipo de acceso.

• Las bibliotecas cliente de Azure son 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 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 es:
  • Trabajar con servicios en versión preliminar que no tienen bibliotecas cliente de Azure disponibles. Considere el código como versión preliminar, que debe actualizarse cuando el servicio esté disponible con carácter general con las bibliotecas cliente.
  • Quiere realizar llamadas REST directamente porque no quiere que todo el SDK use una sola API REST o quiera un mayor control sobre las solicitudes HTTP.

Bibliotecas de administración y cliente de Azure

Las versiones de la biblioteca cliente de Azure están disponibles como:

• Administración: las bibliotecas de administración permiten crear y administrar recursos de Azure. Puede reconocer estas bibliotecas por arm- en sus nombres de paquete. El término arm indica Azure Resource Manager.
  • Documentación y ejemplos de código
• Cliente: dado que ya existe un recurso de Azure, use las bibliotecas cliente para consumirlo e interactuar con él.
  • Cada paquete README.md incluye documentación y ejemplos.

Instalación de paquetes de npm de Azure

Las bibliotecas cliente de Azure están disponibles gratuitamente en NPM y Yarn. Instale los SDK individuales según sea necesario. Cada SDK proporciona definiciones de TypeScript.

Para el uso de cliente o navegador, es necesario agregar las 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 el paquete. Consulte la documentación del paquete específico que usa para obtener información sobre cómo usarlas.

Proporcionar credenciales de autenticación

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

• Incorporación rápida
• Método más seguro
• Separe el mecanismo de autenticación del código. Esto le permite usar el mismo código localmente y en la plataforma Azure, mientras que las credenciales son diferentes.
• Proporcione autenticación encadenada para que haya varios mecanismos disponibles.

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

Una vez que cree una credencial mediante programación, pase la credencial al cliente de Azure. El cliente puede requerir 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 @azure/arm-resources biblioteca cliente para enumerar los grupos de recursos a los que esta credencial tiene acceso para leer.

import { DefaultAzureCredential } from "@azure/identity";
import { ResourceManagementClient } from "@azure/arm-resources";

const subscriptionId = process.env.AZURE_SUBSCRIPTION_ID!;
if (!subscriptionId) {
  throw new Error("AZURE_SUBSCRIPTION_ID environment variable is not set.");
}

console.log(`Using Subscription ID: ${subscriptionId}`);

async function main() {

    const credential = new DefaultAzureCredential();
    const client = new ResourceManagementClient(credential, subscriptionId);

    let i=0;

    for await (const item of client.resourceGroups.list()) {
        console.log(`${++i}: ${item.name}`);
    }
    console.log(`Found ${i} resource group(s).`);
}

main().catch((err) => {
  console.error(err);
});

Paginación asincrónica de resultados

Un método sdk puede devolver un iterador asincrónico, PagedAsyncIterableIterator, para permitir resultados asincrónicos. Los resultados pueden utilizar tokens de paginación y continuación para segmentar 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 rápidamente y visualmente el proceso al ejecutar el código de ejemplo en 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)
);

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

• Iteradores asincrónicos en el SDK de Azure para JavaScript/TypeScript

Operaciones de larga duración

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

• La solicitud se completó
• 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 .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 proporciona clases AbortController y AbortSignal. Utiliza AbortController para crear un AbortSignal, que luego se puede pasar a las operaciones del SDK de Azure para cancelar cualquier trabajo pendiente. Las operaciones del SDK de Azure pueden ser:

• Abortado según tu propia lógica
• Abortado debido a un límite de tiempo de espera
• Abortado en función de la señal de una tarea principal
• Anulado en función de la señal de una tarea primaria o un límite de tiempo de espera

Aprende más:

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

Registro verboso desde el SDK

Al usar el SDK de Azure, 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/registrador :

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

Unión

Obtenga información sobre la agrupación con el SDK de Azure:

• Para agrupar los SDK de Azure
• Agrupamiento de muestras

Pasos siguientes

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