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 inserir, inspecionar, obter e excluir 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 clientes de Armazenamento de Filas do Azure para Python. Para obter mais informações sobre filas, consulte a seção Próximas etapas .
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:
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.
Baixe e instale o SDK do Armazenamento do Azure para Python
O SDK do Armazenamento do Azure para Python requer o Python v2.7, v3.3 ou posterior.
Instalar por meio de PyPi
Para instalar por meio do Índice de Pacote do Python (PyPI), digite:
pip install azure-storage-queue
Observação
Se você estiver fazendo upgrade do SDK de Armazenamento do Azure para Python v0.36 ou anterior, desinstale o SDK mais antigo em uso pip uninstall azure-storage antes de instalar o pacote mais recente.
Para métodos de instalação alternativos, confira o SDK do Armazenamento 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:
Entre no portal do Azure.
Localize sua cadeia de conexão.
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.
No painel Chaves de acesso, selecione Mostrar chaves.
Na seção key1, localize o valor 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 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>"
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 que você queira acessar de forma programática:
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 gerar um identificador exclusivo para um nome de fila.
Criar uma fila
A cadeia de conexão é recuperada a partir da variável AZURE_STORAGE_CONNECTION_STRING de ambiente definida anteriormente.
O código a seguir cria um objeto QueueClient usando a cadeia de conexão da conta 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 do 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)
Espiar mensagens
Você pode inspecionar as mensagens na fila sem removê-las da fila recorrendo ao método peek_messages. Por padrão, esse método inspeciona 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 o conteúdo de uma mensagem in-loco 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_messagepara atualizar uma mensagem. O tempo limite de visibilidade está definido como 0, indicando que a mensagem será exibida imediatamente e o conteúdo será 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 tamanho 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 é aproximado apenas porque as mensagens podem ser adicionadas ou removidas depois que o serviço responde à sua solicitação.
Remover mensagens da fila
É possível remover uma mensagem da fila em duas etapas. Se o seu código não processar uma mensagem, esse processo de duas etapas garantirá que você possa obter a mesma mensagem e tentar novamente. Recorra a delete_message depois que a mensagem tiver sido processada com êxito.
Quando você recorrer ao comando receive_messages, você receberá a próxima mensagem na fila por padrão. Uma mensagem retornada de receive_messages torna-se invisível para todas as outras mensagens de leitura de código da fila. Por padrão, essa mensagem permanece invisível por 30 segundos. Para concluir a remoção da mensagem da fila, chame também 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 da mensagem de uma fila. Primeiro, você pode obter um lote de mensagens (até 32). Segundo, você pode definir um tempo limite de invisibilidade mais longo ou mais curto, permitindo mais ou menos tempo para seu código processar totalmente cada mensagem.
O exemplo de código a seguir usa o método receive_messages para receber mensagens em lotes. Em seguida, ele processa cada mensagem em cada lote usando um for loop aninhado. Ele também define o tempo limite de invisibilidade de 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, recorra ao método delete_queue.
print("Deleting queue: " + queue_client.queue_name)
queue_client.delete_queue()
Dica
Experimente usar o Gerenciador de Armazenamento do Microsoft Azure
O Gerenciador de Armazenamento do Microsoft Azure é um aplicativo autônomo e gratuito da Microsoft que possibilita o trabalho visual com os dados do Armazenamento do Azure no Windows, MacOS e Linux.
Próximas etapas
Agora que você aprendeu os conceitos básicos do Armazenamento de Filas, clique nesse links para saber mais.
- Referência de Armazenamento de Filas do Azure em API para Python
- Central de desenvolvedores do Python
- Referência de API REST do Armazenamento do Azure
Para obter exemplos de código relacionados usando SDKs preteridos do Python versão 2, consulte Exemplos de código usando o Python versão 2.