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
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
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:
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 criarQueueClient
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
, selecioneAdd a permission
e escolhaMicrosoft APIs
. - Escolha
Azure Storage
e marque a caixa de seleção ao lado deuser_impersonation
e clique emAdd 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
eTENANT ID
. Na guia "Certificados & segredos", crie um segredo e anote isso. - Certifique-se de ter
AZURE_TENANT_ID
,AZURE_CLIENT_ID
AZURE_CLIENT_SECRET
como variáveis de ambiente para executar com êxito a amostra (pode aproveitar process.env).
- Na página de visão geral do seu aplicativo AAD, anote o
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 opopReceipt
da 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.
Azure SDK for JavaScript