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 estão no escopo do pacote npm @azure publicado pela microsoft1es.
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 aceder ao 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.
-
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 o seu código como uma versão preliminar, que deve ser atualizada quando o serviço estiver geralmente disponível 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
A biblioteca de cliente do Azure versões estão disponíveis como:
-
Management: As bibliotecas de gerenciamento permitem criar e gerenciar recursos do Azure. Pode reconhecer essas bibliotecas pelo
arm-
nos seus nomes de pacote. O termoarm
indica o Azure Resource Manager. -
Client: 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 e no Yarn. Instale SDKs individuais conforme necessário. Cada SDK fornece definições de TypeScript.
Para uso em cliente/navegador, é necessário adicionar as bibliotecas cliente do Azure ao 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 a documentação específica do pacote 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 necessitar de informações adicionais, como um ID de subscrição ou um endpoint 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 assinatura arm
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 utilizar tokens de paginação e de continuação para dividir os 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:
Operações de longa duração
Um método SDK pode retornar uma operação de longa execução (LRO) resposta bruta. 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:
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 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 devido a um limite de tempo
- Abortado devido ao sinal de uma tarefa principal
- Abortado com base no sinal de uma tarefa pai ou devido a um limite de tempo
Saiba mais:
Registro detalhado do SDK
Quando você estiver usando o SDK do Azure, pode haver momentos em que você precise depurar seu aplicativo.
Para habilitar o registo em tempo de compilação , defina a variável de ambiente AZURE_LOG_LEVEL para
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: