Como usar o Armazenamento de Filas do Azure do Python

Visão geral

Este artigo demonstra cenários comuns usando o serviço de Armazenamento de Filas do Azure. Os cenários abordados incluem inserir, espiar, obter e excluir mensagens de fila. O código para criar e excluir filas também é abordado.

Os exemplos neste artigo são escritos em Python e usam a biblioteca cliente do Azure para Armazenamento de Filas em Python. Para obter mais informações sobre filas, consulte a seção Próximas etapas.

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 processamento assíncrono.

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 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 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 em são endereçáveis utilizando 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, consulte Criar uma conta de armazenamento.

Você também pode criar uma conta de armazenamento do Azure usando do Azure PowerShell, CLI do Azureou 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.

Baixar e instalar o SDK de Armazenamento do Azure para Python

O SDK de Armazenamento do Azure para Python requer Python v2.7, v3.3 ou posterior.

Instalar via PyPI

Para instalar por meio do PyPI (Python Package Index), digite:

pip install azure-storage-queue

Para obter métodos de instalação alternativos, consulte SDK do Azure para Python.

Copiar suas credenciais no Portal do Azure

Quando o aplicativo de exemplo faz uma solicitação para o Armazenamento do Azure, ele precisa ser autorizado. Para autenticar uma solicitação, adicione suas credenciais da conta de armazenamento ao aplicativo como uma cadeia de conexão. Para ver as credenciais da conta de armazenamento, siga estas etapas:

1. Entre no portal do Azure.

2. Localize sua conta de armazenamento.

3. No painel do menu da conta de armazenamento, em Segurança + rede, selecione Chaves de acesso. Aqui, você pode ver as chaves de acesso da conta, bem como a cadeia de conexão completa para cada chave.

   

4. No painel Chaves de acesso, selecione Mostrar chaves.

5. Na seção key1, localize o valor Cadeia de conexão. Selecione o ícone Copiar para a área de transferência para copiar a string de conexão. Você adicionará o valor da cadeia de conexão a uma variável de ambiente na próxima seção.

   

Configurar a cadeia de conexão de armazenamento

Depois de copiar a cadeia de conexão, grave em uma nova variável de ambiente no computador local que executa o aplicativo. Para definir a variável de ambiente, abra uma janela de console e siga as instruções do seu sistema operacional. Substitua <yourconnectionstring> pela cadeia de conexão real.

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Após adicionar a variável de ambiente no Windows, é necessário iniciar uma nova instância da janela de comando.

Reiniciar programas

Depois de adicionar a variável de ambiente, reinicie todos os programas em execução que precisarem ler a variável de ambiente. Por exemplo, reinicie seu ambiente ou editor de desenvolvimento antes de continuar.

Configurar seu aplicativo para acessar o Armazenamento de Filas

O objeto QueueClient permite que você trabalhe com uma fila. Adicione o seguinte código próximo à parte superior de qualquer arquivo Python no qual você deseja acessar programaticamente uma fila do Azure:

from azure.storage.queue import (
        QueueClient,
        BinaryBase64EncodePolicy,
        BinaryBase64DecodePolicy
)

import os, uuid

O pacote os fornece suporte para recuperar uma variável de ambiente. O pacote uuid fornece suporte para gerar um identificador exclusivo para um nome de fila.

Criar uma fila

A cadeia de conexão é recuperada da variável de ambiente AZURE_STORAGE_CONNECTION_STRING definida anteriormente.

O código a seguir cria um objeto QueueClient usando a cadeia de conexão de armazenamento.

# Retrieve the connection string from an environment
# variable named AZURE_STORAGE_CONNECTION_STRING
connect_str = os.getenv("AZURE_STORAGE_CONNECTION_STRING")

# Create a unique name for the queue
q_name = "queue-" + str(uuid.uuid4())

# Instantiate a QueueClient object which will
# be used to create and manipulate the queue
print("Creating queue: " + q_name)
queue_client = QueueClient.from_connection_string(connect_str, q_name)

# Create the queue
queue_client.create_queue()

As mensagens da fila do Azure são armazenadas como texto. Se você quiser armazenar dados binários, configure funções de codificação e decodificação do Base64 antes de colocar uma mensagem na fila.

Configure as funções de codificação e decodificação base64 ao criar o objeto cliente.

# Setup Base64 encoding and decoding functions
base64_queue_client = QueueClient.from_connection_string(
                            conn_str=connect_str, queue_name=q_name,
                            message_encode_policy = BinaryBase64EncodePolicy(),
                            message_decode_policy = BinaryBase64DecodePolicy()
                        )

Inserir uma mensagem em uma fila

Para inserir uma mensagem em uma fila, use o método send_message.

message = u"Hello World"
print("Adding message: " + message)
queue_client.send_message(message)

Dar uma olhadinha nas mensagens

Você pode espiar as mensagens sem removê-las da fila chamando o método peek_messages. Por padrão, esse método espia uma única mensagem.

# Peek at the first message
messages = queue_client.peek_messages()

for peeked_message in messages:
    print("Peeked message: " + peeked_message.content)

Alterar o conteúdo de uma mensagem na fila

Você pode alterar diretamente o conteúdo de uma mensagem na fila. Se a mensagem representar uma tarefa, você poderá usar esse recurso para atualizar o status da tarefa.

O código a seguir usa o método update_message para atualizar uma mensagem. O tempo limite de visibilidade é definido como 0, o que significa que a mensagem é exibida imediatamente e o conteúdo é atualizado.

messages = queue_client.receive_messages()
list_result = next(messages)

message = queue_client.update_message(
        list_result.id, list_result.pop_receipt,
        visibility_timeout=0, content=u'Hello World Again')

print("Updated message to: " + message.content)

Obter o comprimento da fila

Você pode obter uma estimativa do número de mensagens em uma fila.

O método get_queue_properties retorna propriedades de fila, incluindo o approximate_message_count.

properties = queue_client.get_queue_properties()
count = properties.approximate_message_count
print("Message count: " + str(count))

O resultado só é aproximado porque as mensagens podem ser adicionadas ou removidas depois que o serviço responde à sua solicitação.

Desequenciar mensagens

Remova uma mensagem de uma fila em duas etapas. Se o código não processar uma mensagem, esse processo de duas etapas garantirá que você possa obter a mesma mensagem e tentar novamente. Chame delete_message depois que a mensagem tiver sido processada com êxito.

Quando você chama receive_messages, você recebe a próxima mensagem na fila por padrão. Uma mensagem retornada de receive_messages torna-se invisível para qualquer outro código que leia mensagens dessa fila. Por padrão, essa mensagem permanece invisível por 30 segundos. Para concluir a remoção da mensagem da fila, você também deve chamar delete_message.

messages = queue_client.receive_messages()

for message in messages:
    print("Dequeueing message: " + message.content)
    queue_client.delete_message(message.id, message.pop_receipt)

Há duas maneiras de personalizar a recuperação de mensagens de uma fila. Primeiro, você pode obter um lote de mensagens (até 32). Em segundo lugar, 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 receive_messages para obter mensagens em lotes. Em seguida, ele processa cada mensagem em cada lote usando um loop aninhado de for. Ele também define o tempo limite de invisibilidade como cinco minutos para cada mensagem.

messages = queue_client.receive_messages(messages_per_page=5, visibility_timeout=5*60)

for msg_batch in messages.by_page():
   for msg in msg_batch:
      print("Batch dequeue message: " + msg.content)
      queue_client.delete_message(msg)

Excluir uma fila

Para excluir uma fila e todas as mensagens contidas nela, chame o método delete_queue.

print("Deleting queue: " + queue_client.queue_name)
queue_client.delete_queue()

Próximas etapas

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

• Referência da API Python do Armazenamento de Filas do Azure
• Central de desenvolvedores do Python
• Referência da API REST do Azure Storage

Para obter exemplos de código relacionados usando SDKs do Python versão 2 preteridos, consulte Exemplos de código usando o Python versão 2.