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 escopo com o escopo do pacote npm @azure 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 de acessar seu serviço do Azure. Os SDKs do Azure abstraem o código clichê necessário para gerenciar solicitações REST da plataforma Azure baseadas em nuvem, como autenticação, tentativas e registro.
• As APIs REST do Azure são o método preferencial se você estiver:
  • Trabalhando com serviços de visualização que não têm SDKs do Azure disponíveis. Considere seu código como visualização, que deve ser atualizada quando o serviço estiver disponível em geral com SDKs.
  • Deseja fazer chamadas REST diretamente porque não quer que todo o SDK use uma única API REST ou porque deseja um controle mais profundo sobre as solicitações HTTP.

Cliente do Azure e bibliotecas de gerenciamento

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 Azure Resource Manager (ARM). Você pode reconhecer essas bibliotecas em seus nomes de @azure/arm- pacote.
  • Documentação e exemplos de código
• SDKs de cliente: dado 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 amostras.

Instalar pacotes npm do Azure

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

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

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

Cada pacote inclui documentação para você começar rapidamente a usá-lo. 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 autenticar na plataforma 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 Azure enquanto as credenciais são diferentes.
• Fornecer autenticação encadeada para que vários mecanismos possam estar disponíveis

Criar um cliente SDK e métodos de chamada

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

Liste as assinaturas que essa credencial tem acesso para ler.

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 dos 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 continuação para dividir conjuntos de resultados.

O exemplo JavaScript a seguir demonstra a paginação assíncrona. O código define um tamanho de paginação artificialmente curto de 2 para demonstrar rápida e visualmente o processo quando você executa 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 operação de longa execução (LRO). Esta resposta inclui informações incluindo:

• O seu pedido concluído
• O seu pedido ainda está em processo

O exemplo 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 longa duração no Azure:

• @azure/core-lro

Cancelando operações assíncronas

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

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

Saiba mais:

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

Registro detalhado do SDK

Ao usar um SDK do Azure, pode haver momentos em que você precise depurar seu aplicativo.

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

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

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

Agregação

Saiba mais sobre a agregação com o SDK do Azure:

• Para agrupar os SDKs do Azure
• Agregação de amostras

Próximos passos

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