Biblioteca de cliente da Fila de Armazenamento do Azure para JavaScript - versão 12.23.0

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

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

Use as bibliotecas de cliente neste pacote para:

• Obter/Definir Propriedades do Serviço de Fila
• Criar/Listar/Excluir filas
• Enviar/Receber/Espiar/Limpar/Atualizar/Excluir Mensagens da Fila

Ligações principais:

• Código fonte
• Pacote (npm)
• de documentação de referência da API
• Documentação do produto
• Amostras
• APIs REST da fila de armazenamento do Azure

Primeiros passos

Ambientes atualmente suportados

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

Consulte o nosso de 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 cliente da Fila de Armazenamento do Azure para JavaScript é usar o gerenciador de pacotes npm. Digite o seguinte em uma janela do 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 Ative Directory
• Chave compartilhada
• Assinaturas de acesso compartilhado

Azure Ative Directory

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

Compatibilidade

Esta biblioteca é compatível com Node.js e navegadores, e validada em relação às versões LTS Node.js (>= 8.16.0) e versões mais recentes do Chrome, Firefox e Edge.

Trabalhadores da Web

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

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

Essa biblioteca depende das seguintes APIs DOM que precisam de polipreenchimentos externos carregados quando usados em web workers:

• document
• DOMParser
• Node
• XMLSerializer

Diferenças entre Node.js e navegadores

Há diferenças entre Node.js e o tempo de execução dos navegadores. Ao começar a usar essa biblioteca, preste atenção às APIs ou classes marcadas com "APENAS DISPONÍVEL EM TEMPO DE EXECUÇÃO NODE.JS" ou "DISPONÍVEL APENAS EM NAVEGADORES".

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

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

Pacote JavaScript

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

CORS

Você precisa configurar regras de de compartilhamento de recursos entre origens (Cross-Origin Resourcesharing) para sua conta de armazenamento se precisar desenvolver para navegadores. Vá para o portal do Azure e o Gerenciador de Armazenamento do Azure, encontre 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. Mas por favor, personalize as configurações cuidadosamente de acordo com suas necessidades 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

Conceitos-chave

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

Os principais tipos de dados na nossa biblioteca relacionados com estes serviços são:

• Um QueueServiceClient representa uma conexão (por meio de uma URL) com uma determinada conta de armazenamento no serviço de 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 e listar filas do serviço.
• Um representa um único de fila de 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. Ele também aceita opcionalmente 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 Ative Directory a partir de um aplicativo cliente - /azure/storage/common/storage-auth-aad-app

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

  • Registrar um novo aplicativo no Azure Ative Directory(no azure-portal) - /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 azure, vá para 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 azure).

• Configuração do ambiente para o exemplo

  • Na página de visão geral do seu aplicativo AAD, anote o CLIENT ID e TENANT ID. Na guia "Certificados & segredos", crie um segredo e anote isso.
  • Certifique-se de ter AZURE_TENANT_ID, AZURE_CLIENT_IDAZURE_CLIENT_SECRET como variáveis de ambiente para executar com êxito a amostra (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
);

[Nota - Os passos acima são apenas para Node.js]

Usando a cadeia de conexão

Como alternativa, você pode instanciar um QueueServiceClient usando o método estático fromConnectionString() com a cadeia de conexão completa como argumento. (A cadeia de conexão pode ser obtida no portal azure.) [DISPONÍVEL APENAS EM TEMPO DE EXECUÇÃO NODE.JS]

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

const connStr = "<connection string>";

const queueServiceClient = QueueServiceClient.fromConnectionString(connStr);

com StorageSharedKeyCredential

Como alternativa, você instancia um QueueServiceClient com um StorageSharedKeyCredential passando nome-conta e chave-conta como argumentos. (O nome da conta e a chave da conta podem ser obtidos no portal azure.) [DISPONÍVEL APENAS EM TEMPO DE EXECUÇÃO NODE.JS]

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 instanciar um QueueServiceClient com uma SAS (assinaturas de acesso compartilhado). Você pode obter o token SAS do 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() {
  let iter1 = queueServiceClient.listQueues();
  let i = 1;
  for await (const item of iter1) {
    console.log(`Queue${i}: ${item.name}`);
    i++;
  }
}

main();

Alternativamente, 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() {
  let 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 filas de iteração, consulte samples/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();

Espreitar uma mensagem

QueueClient.peekMessages() permite ver uma ou mais mensagens na frente da fila. Esta chamada não impede que outro código aceda a 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();

Processar 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 estiver concluído, ligue para queueClient.deleteMessage() com o popReceiptda mensagem .

Se o código não conseguir processar uma mensagem devido a uma falha de hardware ou software, esse processo de duas etapas garante que outra instância do código possa receber a mesma mensagem e tente 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 QueueServiceClient simples está em samples/v12/typescript/src/queueClient.ts.

Solução de 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 tempo de execução chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

Próximos passos

Mais exemplos de código

• Exemplos de armazenamento em fila de
• Casos de teste de armazenamento em fila

Contribuição

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

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