Biblioteca de clientes da Fila de Armazenamento do Azure para JavaScript – versão 12.25.0

A Fila de Armazenamento do Azure fornece mensagens na nuvem entre os componentes do aplicativo. Ao projetar aplicativos para escala, os componentes do aplicativo geralmente são dissociados, para que possam ser dimensionados de forma independente. O armazenamento de filas fornece mensagens assíncronas para comunicação entre componentes do aplicativo, sejam eles em execução na nuvem, na área de trabalho, em um servidor local ou em um dispositivo móvel. O armazenamento de filas também dá suporte ao gerenciamento de tarefas assíncronas e à criação de fluxos de trabalho do processo.

Este projeto fornece uma biblioteca de clientes em JavaScript que facilita o consumo do serviço Fila de Armazenamento do Azure.

Use as bibliotecas de cliente neste pacote para:

• Propriedades do serviço Get/Set Queue
• Criar/Listar/Excluir Filas
• Enviar/Receber/Espiar/Limpar/Atualizar/Excluir Mensagens da Fila

Links de chave:

• código-fonte
• do pacote (npm)
• documentação de referência da API
• documentação do produto
• exemplos de
• APIs REST da Fila de Armazenamento do Azure

Introdução

Ambientes com suporte no momento

• versões lts do Node.js
• Versões mais recentes do Safari, Chrome, Edge e Firefox.

Consulte nossa política de suporte para obter mais detalhes.

Pré-requisitos

• Uma assinatura do Azure
• Uma conta de armazenamento

Instalar o pacote

A maneira preferida de instalar a biblioteca de clientes da Fila de Armazenamento do Azure para JavaScript é usar o gerenciador de pacotes npm. Digite o seguinte em uma janela de terminal:

npm install @azure/storage-queue

Autenticar o cliente

O Armazenamento do Azure dá suporte a várias maneiras de autenticação. Para interagir com o serviço de Armazenamento de Filas do Azure, você precisará criar uma instância de um cliente de Armazenamento – QueueServiceClient ou QueueClient, por exemplo. Consulte exemplos para criar o QueueServiceClient para saber mais sobre autenticação.

• Azure Active Directory
• chave compartilhada
• assinaturas de acesso compartilhado

Azure Active Directory

O serviço de Armazenamento de Filas do Azure dá suporte ao uso do Azure Active Directory para autenticar solicitações para suas APIs. O pacote @azure/identity fornece uma variedade de tipos de credencial que seu aplicativo pode usar para fazer isso. Consulte o README para @azure/identity para obter mais detalhes e exemplos para começar.

Compatibilidade

Essa biblioteca é compatível com Node.js e navegadores e validada em versões de Node.js LTS (>=8.16.0) e versões mais recentes do Chrome, Firefox e Edge.

Web Workers

Essa biblioteca exige que determinados objetos DOM estejam disponíveis globalmente quando usados no navegador, que os trabalhos da Web não disponibilizam por padrão. Você precisará polifilá-los para fazer essa biblioteca funcionar em trabalhos web.

Para obter mais informações, consulte nossa documentação para usar o SDK do Azure para JS no Web Workers

Essa biblioteca depende das seguintes APIs do DOM que precisam de polyfills externos carregados quando usados em trabalhos Web:

• document
• DOMParser
• Node
• XMLSerializer

Diferenças entre Node.js e navegadores

Há diferenças entre Node.js e o runtime dos navegadores. Ao começar a usar essa biblioteca, preste atenção às APIs ou classes marcadas com "SOMENTE DISPONÍVEL EM NODE.JS RUNTIME" ou "SOMENTE DISPONÍVEL EM NAVEGADORES".

Os seguintes recursos, interfaces, classes ou funções só estão disponíveis no Node.js

• Autorização de chave compartilhada com base no nome da conta e na chave da conta
  • StorageSharedKeyCredential
• Geração de SAS (Assinatura de Acesso Compartilhado)
  • generateAccountSASQueryParameters()
  • generateQueueSASQueryParameters()

Pacote JavaScript

Para usar essa biblioteca de clientes no navegador, primeiro você precisa usar um empacotador. Para obter detalhes sobre como fazer isso, consulte nossa documentação de agrupamento .

CORS

Você precisa configurar regras de CORS (Compartilhamento de Recursos entre Origens) para sua conta de armazenamento se precisar desenvolver para navegadores. Acesse o portal do Azure e o Gerenciador de Armazenamento do Azure, localize sua conta de armazenamento, crie novas regras CORS para serviços de blob/fila/arquivo/tabela.

Por exemplo, você pode criar as seguintes configurações de CORS para depuração. Porém, personalize as configurações cuidadosamente de acordo com seus requisitos no ambiente de produção.

• Origens permitidas: *
• Verbos permitidos: DELETE, GET, HEAD, MERGE, POST, OPTIONS, PUT
• Cabeçalhos permitidos: *
• Cabeçalhos expostos: *
• Idade máxima (segundos): 86400

Principais conceitos

Uma fila é um armazenamento de dados dentro de uma conta de serviço fila de armazenamento do Azure para enviar/receber mensagens entre clientes conectados.

Os principais tipos de dados em nossa biblioteca relacionados a esses serviços são:

• Um QueueServiceClient representa uma conexão (por meio de uma URL) com uma determinada conta de armazenamento no serviço Fila de Armazenamento do Azure e fornece APIs para manipular suas filas. Ele é autenticado no serviço e pode ser usado para criar QueueClient objetos, bem como criar, excluir, listar filas do serviço.
• Um QueueClient representa uma única fila na conta de armazenamento. Ele pode ser usado para manipular as mensagens da fila, por exemplo, para enviar, receber e espiar mensagens na fila.

Exemplos

Importar o pacote

Para usar os clientes, importe o pacote para o arquivo:

const AzureStorageQueue = require("@azure/storage-queue");

Como alternativa, importe seletivamente apenas os tipos necessários:

const { QueueServiceClient, StorageSharedKeyCredential } = require("@azure/storage-queue");

Criar o cliente de serviço de fila

O QueueServiceClient requer uma URL para o serviço de fila e uma credencial de acesso. Opcionalmente, ele também aceita algumas configurações no parâmetro options.

com DefaultAzureCredential de @azure/identity pacote

maneira recomendada de instanciar um QueueServiceClient

Configuração: Referência – Autorizar o acesso a blobs e filas com o Azure Active Directory de um aplicativo cliente – /azure/storage/common/storage-auth-aad-app

• Registrar um novo aplicativo do AAD e conceder permissões para acessar o Armazenamento do Azure em nome do usuário conectado

  • Registrar um novo aplicativo no Azure Active Directory(no portal do Azure) – /azure/active-directory/develop/quickstart-register-app
  • Na seção API permissions, selecione Add a permission e escolha Microsoft APIs.
  • Escolha Azure Storage e marque a caixa de seleção ao lado de user_impersonation e clique em Add permissions. Isso permitiria que o aplicativo acessasse o Armazenamento do Azure em nome do usuário conectado.

• Conceder acesso aos dados da Fila de Armazenamento do Azure com RBAC no Portal do Azure

  • Funções RBAC para blobs e filas – /azure/storage/common/storage-auth-aad-rbac-portal.
  • No portal do Azure, acesse sua conta de armazenamento e atribua função de Colaborador de Dados da Fila de Armazenamento ao aplicativo AAD registrado na guia Access control (IAM) (na barra de navegação do lado esquerdo da sua conta de armazenamento no portal do azure).

• Configuração do ambiente para o exemplo

  • Na página de visão geral do aplicativo AAD, anote o CLIENT ID e o TENANT ID. Na guia "Certificados & Segredos", crie um segredo e observe isso.
  • Verifique se você tem AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET como variáveis de ambiente para executar o exemplo com êxito (pode aproveitar process.env).

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

[Observação - As etapas acima são apenas para Node.js]

usando a cadeia de conexão

Como alternativa, você pode criar uma instância de um QueueServiceClient usando o método estático fromConnectionString() com a cadeia de conexão completa como o argumento. (A cadeia de conexão pode ser obtida no portal do azure.) [DISPONÍVEL APENAS EM NODE.JS RUNTIME]

const { QueueServiceClient } = require("@azure/storage-queue");

const connStr = "<connection string>";

const queueServiceClient = QueueServiceClient.fromConnectionString(connStr);

com StorageSharedKeyCredential

Como alternativa, você cria uma instância de um QueueServiceClient com um StorageSharedKeyCredential passando o nome da conta e a chave da conta como argumentos. (O nome da conta e a chave de conta podem ser obtidos no portal do azure.) [DISPONÍVEL APENAS EM NODE.JS RUNTIME]

const { QueueServiceClient, StorageSharedKeyCredential } = require("@azure/storage-queue");

// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";

// Use StorageSharedKeyCredential with storage account and account key
// StorageSharedKeyCredential is only available in Node.js runtime, not in browsers
const sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  sharedKeyCredential,
  {
    retryOptions: { maxTries: 4 }, // Retry options
    telemetry: { value: "BasicSample/V11.0.0" } // Customized telemetry string
  }
);

com token SAS

Além disso, você pode criar uma instância de um QueueServiceClient com uma SAS (assinaturas de acesso compartilhado). Você pode obter o token SAS no Portal do Azure ou gerar um usando generateAccountSASQueryParameters().

const { QueueServiceClient } = require("@azure/storage-queue");
const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net${sas}`
);

Listar filas nesta conta

Use QueueServiceClient.listQueues() função para iterar as filas, com a nova sintaxe for-await-of:

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

async function main() {
  const iter1 = queueServiceClient.listQueues();
  let i = 1;
  for await (const item of iter1) {
    console.log(`Queue${i}: ${item.name}`);
    i++;
  }
}

main();

Como alternativa, sem for-await-of:

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

async function main() {
  const iter2 = queueServiceClient.listQueues();
  let i = 1;
  let item = await iter2.next();
  while (!item.done) {
    console.log(`Queue ${i++}: ${item.value.name}`);
    item = await iter2.next();
  }
}

main();

Para obter um exemplo completo sobre a iteração de filas, consulte exemplos/v12/typescript/listQueues.ts.

Criar uma nova fila

Use QueueServiceClient.getQueueClient() função para criar uma nova fila.

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

const queueName = "<valid queue name>";

async function main() {
  const queueClient = queueServiceClient.getQueueClient(queueName);
  const createQueueResponse = await queueClient.create();
  console.log(
    `Created queue ${queueName} successfully, service assigned request Id: ${createQueueResponse.requestId}`
  );
}

main();

Enviar uma mensagem para a fila

Use sendMessage() para adicionar uma mensagem à fila:

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

const queueName = "<valid queue name>";

async function main() {
  const queueClient = queueServiceClient.getQueueClient(queueName);
  // Send a message into the queue using the sendMessage method.
  const sendMessageResponse = await queueClient.sendMessage("Hello World!");
  console.log(
    `Sent message successfully, service assigned message Id: ${sendMessageResponse.messageId}, service assigned request Id: ${sendMessageResponse.requestId}`
  );
}

main();

Espiar uma mensagem

QueueClient.peekMessages() permite examinar uma ou mais mensagens na frente da fila. Essa chamada não impede que outro código acesse mensagens espiadas.

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

const queueName = "<valid queue name>";

async function main() {
  const queueClient = queueServiceClient.getQueueClient(queueName);
  const peekMessagesResponse = await queueClient.peekMessages();
  console.log(`The peeked message is: ${peekMessagesResponse.peekedMessageItems[0].messageText}`);
}

main();

Processando uma mensagem

As mensagens são processadas em duas etapas.

• Primeira chamada queueClient.receiveMessages(). Isso torna as mensagens invisíveis para outras mensagens de leitura de código dessa fila por um período padrão de 30 segundos.
• Quando o processamento de uma mensagem for concluído, chame queueClient.deleteMessage() com o popReceiptda mensagem.

Se o código não processar uma mensagem devido a uma falha de hardware ou software, esse processo de duas etapas garante que outra instância do seu código possa receber a mesma mensagem e tentar novamente.

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

const queueName = "<valid queue name>";

async function main() {
  const queueClient = queueServiceClient.getQueueClient(queueName);
  const response = await queueClient.receiveMessages();
  if (response.receivedMessageItems.length === 1) {
    const receivedMessageItem = response.receivedMessageItems[0];
    console.log(`Processing & deleting message with content: ${receivedMessageItem.messageText}`);
    const deleteMessageResponse = await queueClient.deleteMessage(
      receivedMessageItem.messageId,
      receivedMessageItem.popReceipt
    );
    console.log(
      `Delete message successfully, service assigned request Id: ${deleteMessageResponse.requestId}`
    );
  }
}

main();

Excluir uma fila

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

const queueName = "<valid queue name>";

async function main() {
  const queueClient = queueServiceClient.getQueueClient(queueName);
  const deleteQueueResponse = await queueClient.delete();
  console.log(
    `Deleted queue successfully, service assigned request Id: ${deleteQueueResponse.requestId}`
  );
}

main();

Um exemplo completo de cenários de QueueServiceClient simples está em exemplos/v12/typescript/src/queueClient.ts.

Solucionando problemas

Habilitar o registro em log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o registro em log pode ser habilitado em runtime chamando setLogLevel no @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Próximas etapas

Mais exemplos de código

• exemplos de armazenamento de filas
• casos de teste de armazenamento de filas

Contribuindo

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

Consulte também guia específico do Armazenamento para obter informações adicionais sobre como configurar o ambiente de teste para bibliotecas de armazenamento.

impressões