Usar SDKs do Azure para JavaScript e TypeScript

Para acessar programaticamente seus serviços do Azure, use os SDKs do Azure para JavaScript. Normalmente, esses SDKs têm o escopo definido com o escopo do pacote @azure npm publicado pelo azure-sdk.

Diferenças entre SDKs e APIs REST

Use as informações a seguir para entender quando usar qual tipo de mecanismo de acesso.

• Os SDKs do Azure são o método preferencial para acessar seu serviço do Azure. Os SDKs do Azure abstraem o código clichê necessário para gerenciar solicitações REST da plataforma do Azure baseadas em nuvem, como autenticação, novas tentativas e registro em log.
• As APIs REST do Azure são o método preferencial se você for:
  • Trabalhar com serviços em versão prévia que não tenham SDKs do Azure disponíveis. Considerar seu código como versão prévia, que deverá ser atualizado quando o serviço estiver em disponibilidade geral com SDKs.
  • Desejar fazer chamadas REST diretamente por não querer que o SDK inteiro use apenas uma API REST ou se você quiser um controle mais profundo sobre as solicitações HTTP.

Bibliotecas de clientes e de gerenciamento do Azure

As versões do SDK do Azure estão disponíveis como:

• SDKs de gerenciamento: as bibliotecas de gerenciamento permitem provisionar e gerenciar recursos do Azure por meio do ARM (Azure Resource Manager). Você pode reconhecer essas bibliotecas por @azure/arm- nos respectivos nomes de pacote.
  • Documentação e exemplos de código
• SDKs de cliente: considerando que um recurso do Azure já existe, você usaria as bibliotecas de cliente para consumi-lo e interagir com ele.
  • Cada pacote README.md inclui documentação e exemplos.

Instalar pacotes npm do Azure

Os SDKs do Azure estão disponíveis gratuitamente no NPM. Instale os SDKs individuais necessários. Cada SDK fornece definições de TypeScript.

Para o uso do cliente/navegador, os SDKs do Azure precisam ser adicionados ao seu processo de agrupamento.

Usar o código de exemplo do pacote npm do Azure

Cada pacote inclui documentação para uma introdução rápida. Consulte os pacotes NPM específicos que você usa para saber como usá-los.

Fornecer credenciais de autenticação

Os SDKs do Azure exigem credenciais para autenticação na plataforma do Azure. As classes de credenciais fornecidas pelo @azure/identity oferecem vários benefícios:

• Integração rápida
• Método mais seguro
• Separe o mecanismo de autenticação do código. Isso permite que você use o mesmo código localmente e na plataforma do Azure, enquanto as credenciais são diferentes.
• Fornecer autenticação encadeada para que vários mecanismos possam estar disponíveis

Criar um cliente do SDK e chamar métodos

Depois de criar uma credencial programaticamente, passe a credencial para o cliente do SDK do Azure. O cliente pode exigir informações adicionais, como uma ID da assinatura ou URL de serviço. Esses valores estão disponíveis no portal do Azure para o seu recurso.

Listar assinaturas às quais essa credencial tem acesso para leitura.

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

Paginação assíncrona de resultados

Um método SDK pode retornar um iterador assíncrono, PagedAsyncIterableIterator, para permitir resultados assíncronos. Os resultados podem usar tokens de paginação e de continuação para separar conjuntos de resultados.

O exemplo de JavaScript a seguir demonstra a paginação assíncrona. O código define um tamanho de paginação artificialmente curto de 2 para demonstrar o processo de maneira rápida e visual quando você executar o código de exemplo na depuração.

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

Saiba mais sobre paginação e iteradores no Azure:

• Iteradores assíncronos no SDK do Azure para JavaScript/TypeScript

Operações de execução prolongada

Um método SDK pode retornar uma resposta de LRO (operação de execução prolongada). Essa resposta inclui informações, incluindo:

• A sua solicitação foi concluída
• A sua solicitação ainda está em processo

O exemplo de JavaScript a seguir demonstra como aguardar a conclusão de um LRO, com .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)
);

Saiba mais sobre operações de execução prolongada no Azure:

• @azure/core-lro

Cancelando operações assíncronas

O pacote @azure/abort-controller fornece as classes AbortController e AbortSignal. Use o AbortController para criar um AbortSignal, que pode ser passado para operações do SDK do Azure para cancelar o trabalho pendente. As operações do SDK do Azure podem ser:

• Anulada com base em sua própria lógica
• Anulada com base em um tempo limite
• Anulada com base no sinal de uma tarefa pai
• Anulada com base no sinal de uma tarefa pai ou em um tempo limite

Saiba mais:

• Como usar sinais de anulação para cancelar operações no SDK do Azure para JavaScript/TypeScript

Log detalhado do SDK

Ao usar um SDK do Azure, pode haver ocasiões em que você precisa depurar seu aplicativo.

• Para habilitar o registro em log no tempo de build, defina a variável de ambiente AZURE_LOG_LEVEL como info.

• Para habilitar o log em tempo de execução, use o pacote @azure/logger :

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

Agrupamento

Saiba mais sobre o agrupamento com o SDK do Azure:

• Para agrupar os SDKs do Azure
• Amostras de agrupamento

Próximas etapas

• Listar assinaturas com o SDK de assinaturas @azure/arm/arm
• Listar operações de recursos recentes com o SDK do @azure/arm-monitor
• Criar uma máquina virtual com o SDK de computação @azure/arm-arm