Como usar o Armazenamento de Filas do Azure a partir 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 inserção, observação, obtenção e exclusão de mensagens da 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 de cliente do Armazenamento de Filas do Azure para Python. Para obter mais informações sobre filas, consulte a secção Próximas Etapas.

O que é armazenamento em fila?

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 de capacidade total de uma conta de armazenamento. O armazenamento em fila é frequentemente usado para criar uma lista de pendências de trabalho para processar de forma assíncrona.

Conceitos do Serviço de Fila

O serviço de 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 Visã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 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 indicando que a mensagem não expira. Se esse parâmetro for omitido, o tempo de vida padrão será de sete dias.

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

  A seguinte URL aponta para uma 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, veja Criar uma conta de armazenamento.

Você também pode criar uma conta de armazenamento do Azure usando do Azure PowerShell, da CLI do Azure ou o Azure Storage Resource Provider for .NET.

Se preferir não criar uma conta de armazenamento no Azure neste momento, você 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 o desenvolvimento do Armazenamento do Azure local.

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 através do Python Package Index (PyPI), digite:

pip install azure-storage-queue

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

Copiar as credenciais do Portal do Azure

Quando o aplicativo de exemplo faz uma solicitação ao Armazenamento do Azure, ele deve ser autorizado. Para autorizar uma solicitação, adicione as credenciais da conta de armazenamento ao aplicativo como uma cadeia de conexão. Para exibir as credenciais da sua conta de armazenamento, siga estas etapas:

1. Inicie sessão no portal Azure.

2. Localize a sua conta de armazenamento.

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

   

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

5. Na seção key1, localize o valor da cadeia de conexão. Selecione o ícone Copiar para a área de transferência, para copiar a cadeia 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 ligação de armazenamento

Depois de copiar a cadeia de conexão, escreva-a em uma nova variável de ambiente na máquina local que executa o aplicativo. Para definir a variável de ambiente, abra uma janela da consola e siga as instruções relevantes para o seu sistema operativo. Substitua <yourconnectionstring> pela cadeia de conexão real.

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Depois de adicionar a variável de ambiente no Windows, você deve 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 precisarão ler a variável de ambiente. Por exemplo, reinicie o ambiente de desenvolvimento ou editor antes de continuar.

Configurar seu aplicativo para acessar o Armazenamento em Fila

O QueueClient objeto permite trabalhar com uma fila. Adicione o seguinte código perto da 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 os pacote fornece suporte para recuperar uma variável de ambiente. O uuid pacote fornece suporte para a geração de um identificador exclusivo para um nome de fila.

Criar uma fila

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

O código a seguir cria um QueueClient objeto 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 as funções de codificação e decodificação 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 numa fila

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

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

Espreite as mensagens

Você pode espiar mensagens sem removê-las da fila chamando o peek_messages método. 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 em fila

Você pode alterar o conteúdo de uma mensagem diretamente 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 aparece 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 é apenas aproximado porque as mensagens podem ser adicionadas ou removidas depois que o serviço responde à sua solicitação.

Retirar mensagens da fila

Remova uma mensagem de uma fila em duas etapas. Se o código não conseguir processar uma mensagem, esse processo de duas etapas garante que você possa receber a mesma mensagem e tentar novamente. Ligue delete_message depois que a mensagem for processada com sucesso.

Quando você chama receive_messages, você recebe a próxima mensagem na fila por padrão. Uma mensagem retornada do receive_messages torna-se invisível para qualquer outro código que lê 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 receber um lote de mensagens (até 32). Em segundo lugar, você pode definir um tempo limite de invisibilidade maior ou menor, permitindo que seu código tenha mais ou menos tempo para processar completamente cada mensagem.

O exemplo de código a seguir usa o receive_messages método para obter mensagens em lotes. Em seguida, processa cada mensagem dentro de cada lote utilizando um ciclo aninhado for. Também define o tempo limite de invisibilidade para 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 delete_queue método.

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

Próximos passos

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

• Referência da API Python do Azure Queue Storage
• Centro de desenvolvedores Python
• Referência da API REST do Armazenamento do Azure

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