Como utilizar o Armazenamento de Filas do Azure a partir do Python
Descrição Geral
Este artigo demonstra cenários comuns com o serviço Armazenamento de Filas do Azure. Os cenários abrangidos incluem inserir, pré-visualizar, obter e eliminar mensagens de fila. O código para criar e eliminar filas também é abrangido.
Os exemplos neste artigo são escritos em Python e utilizam a biblioteca de cliente do Armazenamento de Filas do Azure para Python. Para obter mais informações sobre filas, consulte a secção Passos seguintes .
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:
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.
Transfira e instale 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 através do PyPI
Para instalar através do Python Package Index (PyPI), escreva:
pip install azure-storage-queue
Nota
Se estiver a atualizar a partir do SDK de Armazenamento do Azure para Python v0.36 ou anterior, desinstale o SDK mais antigo utilizando pip uninstall azure-storage antes de instalar o pacote mais recente.
Para obter métodos de instalação alternativos, veja SDK do Azure para Python.
Copiar as credenciais do Portal do Azure
Quando a aplicação de exemplo faz um pedido ao Armazenamento do Azure, tem de ser autorizada. Para autorizar um pedido, adicione as credenciais da conta de armazenamento à aplicação como uma cadeia de ligação. Para ver as credenciais da conta de armazenamento, siga estes passos:
Inicie sessão no portal do Azure.
Localize a sua conta de armazenamento.
No painel de menus da conta de armazenamento, em Segurança + rede, selecione Chaves de acesso. Aqui, pode ver as chaves de acesso da conta e a cadeia de ligação completa para cada chave.
No painel Chaves de acesso , selecione Mostrar chaves.
Na secção key1 , localize o valor cadeia de ligação . Selecione o ícone Copiar para a área de transferência para copiar a cadeia de ligação. Irá adicionar o valor da cadeia de ligação a uma variável de ambiente na secção seguinte.
Configurar a cadeia de ligação de armazenamento
Depois de copiar a cadeia de ligação, escreva-a numa nova variável de ambiente no computador local que executa a aplicação. Para definir a variável de ambiente, abra uma janela da consola e siga as instruções relevantes para o seu sistema operativo. Substitua pela <yourconnectionstring> cadeia de ligação real.
setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"
Depois de adicionar a variável de ambiente no Windows, tem de iniciar uma nova instância da janela de comandos.
Reiniciar programas
Depois de adicionar a variável de ambiente, reinicie todos os programas em execução que precisem de ler a variável de ambiente. Por exemplo, reinicie o seu ambiente de desenvolvimento ou editor antes de continuar.
Configurar a aplicação para aceder ao Armazenamento de Filas
O QueueClient objeto permite-lhe trabalhar com uma fila. Adicione o seguinte código junto à parte superior de qualquer ficheiro Python no qual pretende aceder programaticamente a uma fila do Azure:
from azure.storage.queue import (
QueueClient,
BinaryBase64EncodePolicy,
BinaryBase64DecodePolicy
)
import os, uuid
O os pacote fornece suporte para obter 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 ligação é obtida a AZURE_STORAGE_CONNECTION_STRING partir do conjunto de variáveis de ambiente anteriormente.
O código seguinte cria um QueueClient objeto com a cadeia de ligaçã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 de fila do Azure são armazenadas como texto. Se quiser armazenar dados binários, configure as funções de codificação e descodificação base64 antes de colocar uma mensagem na fila.
Configure as funções de codificação e descodificação base64 ao criar o objeto de 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()
)
Introduzir uma mensagem numa fila
Para inserir uma mensagem numa fila, utilize o send_message método .
message = u"Hello World"
print("Adding message: " + message)
queue_client.send_message(message)
Pré-visualizar mensagens
Pode pré-visualizar as mensagens sem as remover da fila ao chamar o peek_messages método. Por predefinição, este método pré-visualiza 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 os conteúdos de uma mensagem em fila
Pode alterar os conteúdos de uma mensagem no local na fila de espera. Se a mensagem representar uma tarefa, pode utilizar esta funcionalidade para atualizar o estado da tarefa.
O código seguinte utiliza o update_message método para atualizar uma mensagem. O tempo limite de visibilidade está definido como 0, o que significa que a mensagem é apresentada 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
Pode obter uma estimativa do número de mensagens numa fila.
O método get_queue_properties devolve as propriedades da 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 de o serviço responder ao seu pedido.
Desativar mensagens
Remova uma mensagem de uma fila em dois passos. Se o código não conseguir processar uma mensagem, este processo de dois passos garante que pode obter a mesma mensagem e tentar novamente. Ligar delete_message depois de a mensagem ter sido processada com êxito.
Quando chama receive_messages, recebe a mensagem seguinte na fila por predefinição. Uma mensagem devolvida receive_messages torna-se invisível para qualquer outra mensagem de leitura de código desta fila. Por predefinição, esta mensagem permanece invisível durante 30 segundos. Para concluir a remoção da mensagem da fila, também tem de 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)
Existem duas formas através das quais pode personalizar a obtenção de mensagens a partir de uma fila. Em primeiro lugar, pode obter um lote de mensagens (até 32). Em segundo lugar, pode definir um tempo limite de invisibilidade superior ou inferior, dando mais ou menos tempo ao código para processar totalmente cada mensagem.
O seguinte exemplo de código utiliza o receive_messages método para obter mensagens em lotes. Em seguida, processa cada mensagem dentro de cada lote com um ciclo aninhado for . Define também 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)
Eliminar uma fila
Para eliminar uma fila e todas as mensagens contidas na mesma, chame o delete_queue método .
print("Deleting queue: " + queue_client.queue_name)
queue_client.delete_queue()
Dica
Experimentar o Explorador de Armazenamento do Microsoft Azure
O Explorador de Armazenamento do Microsoft Azure é uma aplicação autónoma e gratuita da Microsoft, que lhe permite trabalhar visualmente com dados do Armazenamento do Azure no Windows, macOS e Linux.
Passos seguintes
Agora que aprendeu as noções básicas do Armazenamento de Filas, siga estas ligações para saber mais.
- Referência da API python do Armazenamento de Filas do Azure
- Centro de programadores python
- Referência da API REST do Armazenamento do Azure
Para exemplos de código relacionados com SDKs python preteridos versão 2, veja Exemplos de código com a versão 2 do Python.