Usar bibliotecas de cliente do Azure para JavaScript e TypeScript

Para acessar programaticamente seus serviços do Azure, use as bibliotecas de cliente do Azure para JavaScript. Normalmente, essas bibliotecas têm escopo com o escopo do pacote npm @azure publicado pelo azure-sdk.

Diferenças entre bibliotecas de cliente e APIs REST

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

• As bibliotecas de cliente do Azure são o método preferencial de acessar seu serviço do Azure. Essas bibliotecas 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:
  • Trabalhar com serviços de pré-visualização que não têm bibliotecas de cliente 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 bibliotecas cliente.
  • 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 da biblioteca de cliente do Azure estão disponíveis como:

• Gerenciamento: as bibliotecas de gerenciamento permitem que você crie e gerencie recursos do Azure. Você pode reconhecer essas bibliotecas em seus nomes de arm- pacote. O termo ARM indica o Azure Resource Manager.
  • Documentação e exemplos de código
• Cliente: dado que um recurso do Azure já existe, use 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

As bibliotecas de cliente do Azure estão disponíveis gratuitamente no NPM. Instale SDKs individuais conforme necessário. Cada SDK fornece definições de TypeScript.

Para uso do cliente/navegador, as bibliotecas de cliente do Azure precisam ser adicionadas 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

As bibliotecas de cliente 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.
• Forneça 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 seu cliente do Azure. O cliente pode exigir informações adicionais, como um ID de assinatura ou ponto de extremidade de serviço. Esses valores estão disponíveis no portal do Azure, para seu recurso.

O exemplo de código a seguir usa o DefaultAzureCredential e a biblioteca de cliente de arm assinatura para listar 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 bruta 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