Como usar o Armazenamento de Filas do Ruby

Visão geral

Este guia mostra como executar cenários comuns usando o serviço de Armazenamento de Filas do Microsoft Azure. Os exemplos são gravados usando a API do Ruby Azure. Os cenários abordados incluem inserir, espiar, obter e excluir mensagens de fila, bem como criar e excluir filas.

O que é armazenamento de filas?

O Armazenamento de Filas do Azure é um serviço para armazenar 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 total de capacidade de uma conta de armazenamento. O armazenamento de filas geralmente é usado para criar um acúmulo de tarefas para serem processadas de forma assíncrona.

Conceitos de serviço de fila

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

• Conta de armazenamento: Todo o acesso ao Armazenamento do Azure é feito por meio de uma conta de armazenamento. Para obter mais informações sobre contas de armazenamento, consulte a 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 obter informações sobre filas de nomenclatura, consulte Filas de Nomenclatura e Metadados.

• Mensagem: Uma mensagem, em qualquer formato, de até 64 KB. O tempo máximo que uma mensagem pode permanecer na fila é de 7 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 podem ser endereçáveis usando o seguinte formato de URL: http://<storage account>.queue.core.windows.net/<queue>

  A URL seguinte refere-se a uma fila no diagrama:

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

Crie 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, confira 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 no momento, também poderá usar o emulador de armazenamento do Azurite para executar e testar seu código em um ambiente local. Para obter mais informações, consulte Usar o emulador do Azurite para o desenvolvimento local do Armazenamento do Azure.

Criar um aplicativo Ruby

Crie um aplicativo Ruby. Para obter instruções, consulte Criar um aplicativo Ruby no Serviço de Aplicativo no Linux.

Configurar seu aplicativo para acessar o armazenamento

Para usar o Armazenamento do Azure, você precisa baixar e usar o pacote ruby do Azure, que inclui um conjunto de bibliotecas de conveniência que se comunicam com os serviços REST de armazenamento.

Usar RubyGems para obter o pacote

1. Use uma interface de linha de comando, como PowerShell (Windows), Terminal (Mac) ou Bash (Unix).
2. Digite gem install azure na janela de comando para instalar a gema e as dependências.

Importar o pacote

Use o editor de texto favorito, adicione o seguinte à parte superior do arquivo Ruby em que você pretende usar o armazenamento:

require "azure"

Configurar uma conexão de Armazenamento do Azure

O módulo do Azure lerá as variáveis de ambiente AZURE_STORAGE_ACCOUNT e AZURE_STORAGE_ACCESS_KEY para obter informações necessárias para se conectar à sua conta de Armazenamento do Azure. Se essas variáveis de ambiente não estiverem definidas, você deverá especificar as informações da conta antes de usar Azure::QueueService com o seguinte código:

Azure.config.storage_account_name = "<your azure storage account>"
Azure.config.storage_access_key = "<your Azure storage access key>"

Para obter esses valores de uma conta de armazenamento clássica ou do Resource Manager no portal do Azure:

1. Faça logon no portal do Azure.
2. Navegue até a conta de armazenamento que você deseja usar.
3. Na folha Configurações à direita, clique em Chaves de Acesso.
4. Na folha Chaves de Acesso exibida, você verá a chave de acesso 1 e a chave de acesso 2. Você pode usar qualquer um deles.
5. Clique no ícone de cópia para copiar a chave para a área de transferência.

Como criar uma fila

O código a seguir cria um objeto Azure::QueueService, que permite que você trabalhe com filas.

azure_queue_service = Azure::QueueService.new

Use o método create_queue() para criar uma fila com o nome especificado.

begin
  azure_queue_service.create_queue("test-queue")
rescue
  puts $!
end

Como inserir uma mensagem em uma fila

Para inserir uma mensagem em uma fila, use o método create_message() para criar uma nova mensagem e adicioná-la à fila.

azure_queue_service.create_message("test-queue", "test message")

Como espiar a próxima mensagem

Você pode espiar a mensagem na frente de uma fila sem removê-la da fila chamando o método peek_messages(). Por padrão, o peek_messages() inspeciona uma única mensagem. Você também pode especificar quantas mensagens deseja visualizar.

result = azure_queue_service.peek_messages("test-queue",
  {:number_of_messages => 10})

Como desativar a próxima mensagem

Você pode remover uma mensagem de uma fila em duas etapas.

1. Quando você chama list_messages(), você recebe a próxima mensagem em uma fila por padrão. Você também pode especificar quantas mensagens deseja obter. As mensagens retornadas de list_messages() se tornam invisíveis para qualquer outro código que leia mensagens dessa fila. Você passa o tempo limite de visibilidade em segundos como um parâmetro.
2. Para concluir a remoção da mensagem da fila, você também deve chamar delete_message().

Esse processo de duas etapas de remoção de uma mensagem garante que, quando o código não processa uma mensagem devido a uma falha de hardware ou software, outra instância do seu código pode receber a mesma mensagem e tentar novamente. Seu código chama delete_message() imediatamente após o processamento da mensagem.

messages = azure_queue_service.list_messages("test-queue", 30)
azure_queue_service.delete_message("test-queue",
  messages[0].id, messages[0].pop_receipt)

Como alterar o conteúdo de uma mensagem na fila

Você pode alterar diretamente o conteúdo de uma mensagem na fila. O código a seguir usa o método update_message() para atualizar uma mensagem. O método retornará uma tupla que contém o recebimento pop da mensagem de fila e um valor de DateTime UTC que representa quando a mensagem ficará visível na fila.

message = azure_queue_service.list_messages("test-queue", 30)
pop_receipt, time_next_visible = azure_queue_service.update_message(
  "test-queue", message.id, message.pop_receipt, "updated test message",
  30)

Como: opções adicionais para desativar mensagens

Há duas maneiras de personalizar a recuperação de mensagens de uma fila.

1. Você pode obter um lote de mensagens.
2. Você pode definir um tempo limite de invisibilidade mais longo ou menor, permitindo que seu código tenha mais ou menos tempo para processar totalmente cada mensagem.

O exemplo de código a seguir usa o método list_messages() para obter 15 mensagens em uma chamada. Em seguida, ele imprime e exclui cada mensagem. Ele também define o tempo limite de invisibilidade como cinco minutos para cada mensagem.

azure_queue_service.list_messages("test-queue", 300
  {:number_of_messages => 15}).each do |m|
  puts m.message_text
  azure_queue_service.delete_message("test-queue", m.id, m.pop_receipt)
end

Como obter o comprimento da fila

Você pode obter uma estimativa do número de mensagens na fila. O método get_queue_metadata() retorna a contagem aproximada de mensagens e outros metadados de fila.

message_count, metadata = azure_queue_service.get_queue_metadata(
  "test-queue")

Como excluir uma fila

Para excluir uma fila e todas as mensagens contidas nela, chame o método delete_queue() no objeto de fila.

azure_queue_service.delete_queue("test-queue")

Próximas etapas

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

• Visite o blog da equipe de Armazenamento do Azure
• Visite o repositório do SDK do Azure para Ruby no GitHub

Para obter uma comparação entre o Armazenamento de Filas do Azure discutido neste artigo e as Filas do Barramento de Serviço do Azure discutidas em Como usar Filas do Barramento de Serviço, consulte Armazenamento de Filas do Azure e Filas do Barramento de Serviço – comparados e contrastados