Partilhar via

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

  • Artigo

Descrição Geral

Este guia mostra-lhe como realizar cenários comuns com o Armazenamento de Filas do Azure. Os exemplos são escritos com a API de Node.js. Os cenários abrangidos incluem inserir, pré-visualizar, obter e eliminar mensagens de fila. Saiba também como criar e eliminar filas.

O que é o Armazenamento de filas?

O Armazenamento de Filas do Azure é um serviço para armazenar um grande número de mensagens que podem ser acedidas a partir de qualquer local no mundo através de chamadas autenticadas com HTTP ou HTTPS. Uma mensagem de fila única pode ter até 64 KB e uma fila pode conter milhões de mensagens, até ao limite da capacidade total de uma conta de armazenamento. O armazenamento de filas é frequentemente utilizado para criar um registo de tarefas pendentes para processar de forma assíncrona.

Conceitos de serviço de fila

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

Componentes do serviço fila do Azure

  • Conta de Armazenamento: todos os acessos ao Storage do Azure são efetuados através de uma conta de armazenamento. Para obter mais informações sobre contas de armazenamento, veja Descrição geral da conta de armazenamento.

  • Fila: uma fila contém um conjunto de mensagens. Todas as mensagens têm de estar numa fila. Tenha em atenção que o nome da fila tem de estar todo em minúsculas. Para obter informações sobre a nomenclatura de filas, veja Nomenclatura de Filas e Metadados.

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

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

    O seguinte URL endereça uma fila no diagrama:

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

Criar uma conta de armazenamento do Azure

A forma mais fácil de criar a primeira conta de armazenamento do Azure é com o portal do Azure. Para saber mais, veja Criar uma conta de armazenamento.

Também pode utilizar o Azure PowerShell, a CLI do Azure ou o Fornecedor de Recursos do Armazenamento do Azure para .NET.

Se preferir não criar uma conta de armazenamento no Azure neste momento, também pode utilizar o emulador de armazenamento do Azurite para executar e testar o código num ambiente local. Para obter mais informações, veja Utilizar o emulador do Azurite para o desenvolvimento local do Armazenamento do Azure.

Criar uma aplicação Node.js

Para criar uma aplicação Node.js em branco, veja Criar uma aplicação Web Node.js no Serviço de Aplicações do Azure, criar e implementar uma aplicação Node.js no Azure Serviços Cloud com o PowerShell ou o Visual Studio Code.

Configurar a aplicação para aceder ao armazenamento

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

Utilizar o Gestor de pacotes de nós (npm) para obter o pacote

  1. Utilize uma interface de linha de comandos, como o PowerShell (Windows), Terminal (Mac) ou Bash (Unix), navegue para a pasta onde criou a sua aplicação de exemplo.

  2. Escreva npm install @azure/storage-queue na janela de comandos.

  3. Verifique se foi criada uma node_modules pasta. Nessa pasta, encontrará o @azure/storage-queue pacote, que contém a biblioteca de cliente de que precisa para aceder ao armazenamento.

Importar o pacote

Com o editor de código, adicione o seguinte ao ficheiro JavaScript superior onde pretende utilizar filas.

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

Como criar uma fila

O código seguinte obtém o valor de uma variável de ambiente chamada AZURE_STORAGE_CONNECTION_STRING e utiliza-o para criar um QueueServiceClient objeto. Em seguida, este objeto é utilizado para criar um QueueClient objeto que lhe permite trabalhar 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, é emitida uma exceção.

Como formatar a mensagem

O tipo de mensagem é uma cadeia. Todas as mensagens são tratadas como cadeias de carateres. Se precisar de enviar um tipo de dados diferente, terá de serializar esse tipo de dados numa cadeia ao enviar a mensagem e anular a serialização do formato da cadeia ao ler a mensagem.

Para converter JSON num formato de cadeia e voltar novamente ao Node.js, utilize 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 numa fila

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

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

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

Como pré-visualizar a mensagem seguinte

Pode pré-visualizar as mensagens na fila sem as remover da fila ao chamar o peekMessages método.

Por predefinição, peekMessages espreite uma única mensagem. O exemplo seguinte espreita as primeiras cinco mensagens na fila. Se forem visíveis menos de cinco mensagens, são devolvidas apenas as mensagens visíveis.

// 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);
}

As chamadas peekMessages quando não existem mensagens na fila não devolvem um erro. No entanto, não são devolvidas mensagens.

Como alterar o conteúdo de uma mensagem em fila

O exemplo seguinte atualiza o texto de uma mensagem.

Altere o conteúdo de uma mensagem no local na fila ao chamar 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 desativar uma mensagem

A desaconsultação de uma mensagem é um processo de duas fases:

  1. Obtenha a mensagem.

  2. Elimine a mensagem.

O exemplo seguinte recebe uma mensagem e, em seguida, elimina-a.

Para obter uma mensagem, chame o receiveMessages método . Esta chamada torna as mensagens invisíveis na fila, pelo que nenhum outro cliente pode processá-las. Assim que a sua aplicação tiver processado uma mensagem, chame deleteMessage para eliminá-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 predefinição, uma mensagem só está ocultada durante 30 segundos. Após 30 segundos, fica visível para outros clientes. Pode especificar um valor diferente ao definir options.visibilityTimeout quando chama receiveMessages.

As chamadas receiveMessages quando não existem mensagens na fila não devolvem um erro. No entanto, não serão devolvidas mensagens.

Opções adicionais para descodificação de mensagens

Existem duas formas de personalizar a obtenção de mensagens a partir de uma fila:

O exemplo seguinte utiliza o receiveMessages método para obter cinco mensagens numa chamada. Em seguida, processa cada mensagem com um for ciclo. Também define o tempo limite de invisibilidade para cinco minutos para todas as mensagens devolvidas 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 getProperties método devolve 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 obter uma lista de filas, chame QueueServiceClient.listQueues. Para obter uma lista filtrada por um prefixo específico, defina options.prefix na sua chamada para listQueues.

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

Como eliminar uma fila

Para eliminar uma fila e todas as mensagens contidas na mesma, chame o DeleteQueue método no QueueClient objeto.

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

Para limpar todas as mensagens de uma fila sem a eliminar, chame ClearMessages.

Dica

Veja o repositório de amostras de código do Armazenamento do Azure

Para obter exemplos de código de Armazenamento do Azure ponto a ponto fáceis de utilizar que pode transferir e executar, veja a nossa lista de Exemplos de Armazenamento do Azure.

Passos seguintes

Agora que aprendeu as noções básicas do Armazenamento de Filas, siga estas ligações para saber mais sobre tarefas de armazenamento mais complexas.