Uso de Azure SDK para JavaScript y TypeScript

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

Diferencias entre los SDK y las API REST

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

• 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 es:
  • 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.
  • Documentación y ejemplos de código
• 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");
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 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 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 proporciona 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/registrador :

  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

• Enumeración de suscripciones con el SDK de @azure/arm-subscriptions
• Enumeración de las operaciones de recursos recientes con el SDK de @azure/arm-monitor
• Creación de una máquina virtual con @azure/arm-compute SDK