Compartilhar via

Como usar o Armazenamento de Filas do Azure a partir do Node.js

  • Artigo

Visão geral

Este guia mostra como realizar cenários comuns usando o Armazenamento de Filas do Azure. As amostras são gravadas usando a API do Node.js. Os cenários abordados incluem inserir, inspecionar, obter e excluir mensagens da fila. Saiba também como criar e excluir filas.

O que é armazenamento em fila?

O armazenamento de filas do Azure é um serviço para armazenamento de um grande número de mensagens que podem ser acessadas de qualquer lugar do mundo por meio de chamadas autenticadas usando HTTP ou HTTPS. Uma única mensagem de fila pode ter até 64 KB de tamanho e uma fila pode conter milhões de mensagens, até o limite de capacidade total de uma conta de armazenamento. O armazenamento em fila é usado com frequência para criar uma lista de pendências de trabalho a ser processada de forma assíncrona.

Conceitos do serviço Fila

O serviço Fila do Azure contém os seguintes componentes:

Componentes do serviço Fila do Azure

  • Conta de Armazenamento: todo o acesso ao Armazenamento do Azure é feito através de uma conta de armazenamento. Para saber mais sobre as contas de armazenamento, confira Visão geral da conta de armazenamento.

  • Fila: uma fila contém um conjunto de mensagens. Todas as mensagens devem estar em uma fila. Observe que o nome da fila deve estar em letras minúsculas. Para saber mais sobre filas de nomenclatura, confira Nomenclatura de filas e metadados.

  • Mensagem: uma mensagem, em qualquer formato, de até 64 KB. O tempo máximo que uma mensagem pode ficar na fila é de sete dias. Para a versão 2017-07-29 ou posterior, a vida útil máxima pode ser qualquer número positivo ou -1, indicando que a mensagem não expira. Se esse parâmetro for omitido, a vida útil padrão será de sete dias.

  • Formato de URL: as filas são endereçáveis usando o seguinte formato: http://<storage account>.queue.core.windows.net/<queue>

    A URL a seguir endereça um fila no diagrama:

    http://myaccount.queue.core.windows.net/incoming-orders

Criar uma conta de armazenamento do Azure

A maneira mais fácil de criar sua primeira conta de armazenamento do Azure é usando o portal do Azure. Para saber mais, consulte Criar uma conta de armazenamento.

Você também pode criar uma conta de armazenamento do Azure usando o Azure PowerShell, a CLI do Azure ou o Provedor de Recursos de Armazenamento do Azure para .NET.

Se você preferir não criar uma conta de armazenamento no Azure neste momento, também pode usar o emulador de armazenamento Azurite para executar e testar seu código em um ambiente local. Para obter mais informações, consulte Usar o emulador Azurite para desenvolvimento local do armazenamento do Azure.

Criar um aplicativo do Node.js

Para criar um aplicativo em branco do Node.js, consulte Criar um aplicativo Web do Node.js no Serviço de Aplicativo do Azure e criar e implantar um aplicativo do Node.js nos Serviços de Nuvem do Azure usando o PowerShell ou o Visual Studio Code.

Configurar seu aplicativo para acessar o armazenamento

A biblioteca de clientes do Armazenamento do Azure para JavaScript inclui um conjunto de bibliotecas de conveniência que se comunicam com os serviços REST de armazenamento.

Usar o npm (gerenciador de pacotes de nós) para obter o pacote

  1. Use uma interface de linha de comando, como PowerShell (Windows), Terminal (Mac) ou Bash (Unix), e navegue até a pasta onde você criou o aplicativo de exemplo.

  2. Digite npm install @azure/storage-queue na janela comando.

  3. Verifique se uma pasta node_modules foi criada. Dentro dessa pasta, você encontrará o pacote @azure/storage-queue que contém a biblioteca do cliente necessária para acessar o armazenamento.

Importar o pacote

Usando seu editor de código, adicione o seguinte na parte superior do arquivo JavaScript no qual você pretende usar as filas.

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

Como criar uma fila

O código a seguir obtém o valor de uma variável de ambiente chamada AZURE_STORAGE_CONNECTION_STRING e o usa para criar um objeto QueueServiceClient. Então, esse objeto é usado para criar um objeto QueueClient que permite que você trabalhe com uma fila específica.

// Retrieve the connection from an environment
// variable called AZURE_STORAGE_CONNECTION_STRING
const connectionString = process.env.AZURE_STORAGE_CONNECTION_STRING;

// Create a unique name for the queue
const queueName = "myqueue-" + Date.now().toString();

console.log("Creating queue: ", queueName);

// Instantiate a QueueServiceClient which will be used
// to create a QueueClient and to list all the queues
const queueServiceClient = QueueServiceClient.fromConnectionString(connectionString);

// Get a QueueClient which will be used
// to create and manipulate a queue
const queueClient = queueServiceClient.getQueueClient(queueName);

// Create the queue
await queueClient.create();

Se a fila já existir, será gerada uma exceção.

Como formatar a mensagem

O tipo de mensagem é uma cadeia de caracteres. Todas as mensagens são tratadas como cadeias de caracteres. Se você precisar enviar um tipo de dados diferente, precisará serializar esse tipo de dados em uma cadeia de caracteres ao enviar a mensagem e desserializar o formato de cadeia de caracteres ao ler a mensagem.

Para converter JSON em um formato de cadeia de caracteres e voltar novamente em Node.js, use as seguintes funções auxiliares:

function jsonToBase64(jsonObj) {
    const jsonString = JSON.stringify(jsonObj)
    return  Buffer.from(jsonString).toString('base64')
}
function encodeBase64ToJson(base64String) {
    const jsonString = Buffer.from(base64String,'base64').toString()
    return JSON.parse(jsonString)
}

Como inserir uma mensagem em uma fila

Para adicionar uma mensagem a uma fila, chame o método sendMessage.

messageText = "Hello, World";
console.log("Adding message to the queue: ", messageText);

// Add a message to the queue
await queueClient.sendMessage(messageText);

Como espiar a próxima mensagem

Você pode inspecionar as mensagens na fila sem removê-las da fila chamando o método peekMessages.

Por padrão, o peekMessages inspeciona uma única mensagem. O exemplo a seguir inspeciona as primeiras cinco mensagens na fila. Se menos de cinco mensagens estiverem visíveis, apenas as mensagens visíveis são retornadas.

// Peek at messages in the queue
const peekedMessages = await queueClient.peekMessages({ numberOfMessages: 5 });

for (i = 0; i < peekedMessages.peekedMessageItems.length; i++) {
    // Display the peeked message
    console.log("Peeked message: ", peekedMessages.peekedMessageItems[i].messageText);
}

Chamar peekMessages quando não houver mensagens na fila não retornará um erro. No entanto, nenhuma mensagem é retornada.

Como alterar o conteúdo de uma mensagem em fila

O exemplo a seguir atualiza o texto de uma mensagem.

Altere o conteúdo de uma mensagem in-loco na fila chamando updateMessage.

// Get the first message in the queue
var receivedMessages = await queueClient.receiveMessages();
const firstMessage = receivedMessages.receivedMessageItems[0];

// Update the received message
await queueClient.updateMessage(
    firstMessage.messageId,
    firstMessage.popReceipt,
    "This message has been updated"
);

Como remover mensagens da fila

A remoção de uma mensagem da fila é um processo de duas fases:

  1. Obtenha a mensagem.

  2. Excluir a mensagem.

O exemplo a seguir obtém uma mensagem e, em seguida, a exclui.

Para obter uma mensagem, chame o método receiveMessages. Esta chamada torna as mensagens invisíveis na fila, de forma que nenhum outro cliente possa processá-las. Depois que seu aplicativo tiver processado uma mensagem, chame deleteMessage para excluí-la da fila.

// Get next message from the queue
receivedMessages = await queueClient.receiveMessages();
var message = receivedMessages.receivedMessageItems[0];

console.log("Dequeuing message: ", message.messageText);

await queueClient.deleteMessage(message.messageId, message.popReceipt);

Por padrão, uma mensagem só fica escondida por 30 segundos. Depois de 30 segundos, ela fica visível para outros clientes. Você pode especificar um valor diferente definindo options.visibilityTimeout ao chamar receiveMessages.

Chamar receiveMessages quando não houver mensagens na fila não retornará um erro. No entanto, nenhuma mensagem será retornada.

Opções adicionais para remover mensagens da fila

Há duas maneiras de personalizar a recuperação da mensagem de uma fila:

O exemplo a seguir usa o método receiveMessages para receber cinco mensagens em uma chamada. Em seguida, ele processa cada mensagem usando um loop for. Ele também define o tempo limite de invisibilidade de cinco minutos para cada mensagem retornada por este método.

// Get up to 5 messages from the queue
const receivedMsgsResp = await queueClient.receiveMessages({ numberOfMessages: 5, visibilityTimeout: 5 * 60 });

for (i = 0; i < receivedMsgsResp.receivedMessageItems.length; i++)
{
    message = receivedMsgsResp.receivedMessageItems[i];
    console.log("Dequeuing message: ", message.messageText);
    await queueClient.deleteMessage(message.messageId, message.popReceipt);
}

Como obter o comprimento da fila

O método getProperties retorna metadados sobre a fila, incluindo o número aproximado de mensagens em espera na fila.

const properties = await queueClient.getProperties();
console.log("Approximate queue length: ", properties.approximateMessagesCount);

Como listar filas

Para recuperar uma lista de filas, chame QueueServiceClient.listQueues. Para recuperar uma lista filtrada por um prefixo específico, defina options.prefix em sua chamada para listQueues.

for await (const item of queueServiceClient.listQueues()) {
  console.log("Queue: ", item.name);
}

Como excluir uma fila

Para excluir uma fila e todas as mensagens que ela contém, chame o DeleteQueue método no objeto QueueClient.

// Delete the queue
console.log("Deleting queue: ", queueClient.name);
await queueClient.delete();

Para limpar todas as mensagens de uma fila sem excluí-la, chame ClearMessages.

Dica

Confira o repositório de exemplos de código do Armazenamento do Azure

Para exemplos de código fácil de usar ponta a ponta do Armazenamento do Azure que você pode baixar e executar, consulte nossa lista de Exemplos de Armazenamento do Azure.

Próximas etapas

Agora que você aprendeu os conceitos básicos do Armazenamento de Filas, siga estes links para saber mais sobre tarefas de armazenamento mais complexas.