Início Rápido: biblioteca de clientes do Armazenamento de Filas do Azure para Python

Introdução à biblioteca de clientes do Armazenamento de Filas do Azure para Python. O Armazenamento de Filas do Azure é um serviço usado para armazenar grandes quantidades de mensagens para recuperação e processamento posteriores. Siga estas etapas para instalar o pacote e experimentar o código de exemplo para tarefas básicas.

Documentação de referência da API | Código-fonte da biblioteca | Pacote (Índice de Pacote do Python) | Exemplos

Use a biblioteca de clientes do Armazenamento de Filas do Azure para Python a fim de:

• Criar uma fila
• Adicionar mensagens a uma fila
• Espiar mensagens em uma fila
• Atualizar uma mensagem em uma fila
• Obter o tamanho da fila
• Receber mensagens de uma fila
• Excluir mensagens de uma fila
• Excluir uma fila

Pré-requisitos

• Assinatura do Azure - criar uma gratuitamente
• Conta de armazenamento do Azure - criar uma conta de armazenamento
• Python 3.8+

Configurando

Esta seção fornece instruções sobre como preparar um projeto para funcionar com a biblioteca de clientes do Armazenamento de Filas do Azure para Python.

Criar o projeto

Crie um aplicativo Python chamado queues-quickstart.

1. Em uma janela de console (como cmd, PowerShell ou Bash), crie um novo diretório para o projeto.

   mkdir queues-quickstart
   

2. Alterne para o diretório queues-quickstart criado recentemente.

   cd queues-quickstart
   

Instalar os pacotes

No diretório do projeto, instale a biblioteca de clientes do Armazenamento de Filas do Azure no pacote Python usando o comando pip install. O pacote azure-identity é necessário para conexões sem senha com os serviços do Azure.

pip install azure-storage-queue azure-identity

Configurar o framework de aplicativos

1. Abra um arquivo de texto novo no editor de código

2. Adicione instruções import

3. Crie a estrutura do programa, incluindo um tratamento de exceções básico

   O código é o seguinte:

   import os, uuid
   from azure.identity import DefaultAzureCredential
   from azure.storage.queue import QueueServiceClient, QueueClient, QueueMessage, BinaryBase64DecodePolicy, BinaryBase64EncodePolicy
   
   try:
       print("Azure Queue storage - Python quickstart sample")
       # Quickstart code goes here
   except Exception as ex:
       print('Exception:')
       print(ex)
   
   

4. Salve o novo arquivo como queues-quickstart-.py no diretório queues-quickstart.

Autenticar no Azure

As solicitações do aplicativo para a maioria dos serviços do Azure precisam ser autorizadas. O uso da classe DefaultAzureCredential fornecida pela biblioteca de clientes de Identidade do Azure é a abordagem recomendada para implementar conexões sem senha com os serviços do Azure no seu código.

Você também pode autorizar solicitações para serviços do Azure usando senhas, cadeias de conexão ou outras credenciais diretamente. No entanto, essa abordagem deve ser usada com cautela. Os desenvolvedores devem ser diligentes para nunca expor esses segredos em um local não seguro. Qualquer pessoa que tenha acesso à senha ou à chave secreta poderá se autenticar. DefaultAzureCredential oferece benefícios aprimorados de gerenciamento e segurança sobre a chave de conta para permitir a autenticação sem senha. Ambas as opções são demonstradas no exemplo a seguir.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

az role assignment create --assignee "<user@domain>" \
    --role "Storage Queue Data Contributor" \
    --scope "<your-resource-id>"

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Queue Data Contributor" `
    -Scope <yourStorageAccountId>

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Modelo de objeto

O armazenamento de Filas do Azure é um serviço usado para armazenar grandes quantidades de mensagens. Uma mensagem da fila pode ter até 64 KB. Uma fila pode conter milhões de mensagens, até o limite da capacidade total de uma conta de armazenamento. As filas são normalmente usadas para criar uma lista de pendências de trabalho para processamento assíncrono. O Armazenamento de Filas oferece três tipos de recursos:

• 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, consulte 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. Uma mensagem pode ficar na fila por no máximo 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.

O diagrama a seguir mostra a relação entre esses recursos.

Use as classes Python a seguir para interagir com esses recursos:

• QueueServiceClient: O QueueServiceClient permite que você gerencie todas as filas em sua conta de armazenamento.
• QueueClient: A classe QueueClient permite que você gerencie e manipule uma fila individual e as mensagens dela.
• QueueMessage: A classe QueueMessage representa os objetos individuais retornados ao chamar receive_messages em uma fila.

Exemplos de código

Esses snippets de código de exemplo mostram como executar as seguintes ações com a biblioteca de clientes do Armazenamento de Filas do Azure para Python:

• Autorizar acesso e criar um objeto de cliente
• Criar uma fila
• Adicionar mensagens a uma fila
• Espiar mensagens em uma fila
• Atualizar uma mensagem em uma fila
• Obter o tamanho da fila
• Receber mensagens de uma fila
• Excluir mensagens de uma fila
• Excluir uma fila

az login

az login

Connect-AzAccount

from azure.identity import DefaultAzureCredential

    print("Azure Queue storage - Python quickstart sample")

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

    account_url = "https://<storageaccountname>.queue.core.windows.net"
    default_credential = DefaultAzureCredential()

    # Create the QueueClient object
    # We'll use this object to create and interact with the queue
    queue_client = QueueClient(account_url, queue_name=queue_name ,credential=default_credential)

    print("Azure Queue storage - Python quickstart sample")

    # Retrieve the connection string for use with the application. The storage
    # connection string is stored in an environment variable on the machine
    # running the application called AZURE_STORAGE_CONNECTION_STRING. If the
    # environment variable is created after the application is launched in a
    # console or with Visual Studio, the shell or application needs to be
    # closed and reloaded to take the environment variable into account.
    connect_str = os.getenv('AZURE_STORAGE_CONNECTION_STRING')

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

    print("Creating queue: " + queue_name)

    # Instantiate a QueueClient which will be
    # used to create and manipulate the queue
    queue_client = QueueClient.from_connection_string(connect_str, queue_name)

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()
                        )

Criar uma fila

Usando o objeto QueueClient, chame o método create_queue para criar a fila na sua conta de armazenamento.

Adicione este código ao final do bloco try:

    print("Creating queue: " + queue_name)

    # Create the queue
    queue_client.create_queue()

Adicionar mensagens a uma fila

O snippet de código a seguir adiciona mensagens à fila chamando o método send_message. Ele também salva a QueueMessage retornada da terceira chamada send_message. O saved_message é usado para atualizar o conteúdo da mensagem posteriormente no programa.

Adicione este código ao final do bloco try:

    print("\nAdding messages to the queue...")

    # Send several messages to the queue
    queue_client.send_message(u"First message")
    queue_client.send_message(u"Second message")
    saved_message = queue_client.send_message(u"Third message")

Espiar mensagens em uma fila

Espie as mensagens na fila chamando o método peek_messages. Esse método recupera uma ou mais mensagens do início da fila, mas não altera a visibilidade da mensagem.

Adicione este código ao final do bloco try:

    print("\nPeek at the messages in the queue...")

    # Peek at messages in the queue
    peeked_messages = queue_client.peek_messages(max_messages=5)

    for peeked_message in peeked_messages:
        # Display the message
        print("Message: " + peeked_message.content)

Atualizar uma mensagem em uma fila

Atualize o conteúdo de uma mensagem chamando o método update_message. Esse método pode alterar o conteúdo e o tempo limite da visibilidade de uma mensagem. O conteúdo da mensagem precisa ser uma cadeia de caracteres codificada em UTF-8 com até 64 KB. Junto com o novo conteúdo, transmita os valores da mensagem que foi salva anteriormente no código. Os valores de saved_message identificam a mensagem a ser atualizada.

    print("\nUpdating the third message in the queue...")

    # Update a message using the message saved when calling send_message earlier
    queue_client.update_message(saved_message, pop_receipt=saved_message.pop_receipt, \
        content="Third message has been updated")

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, devido ao fato de que as mensagens podem ser adicionadas ou removidas após o serviço responder à sua solicitação.

Receber mensagens de uma fila

Você pode baixar as mensagens adicionadas anteriormente chamando o método receive_messages.

Adicione este código ao final do bloco try:

    print("\nReceiving messages from the queue...")

    # Get messages from the queue
    messages = queue_client.receive_messages(max_messages=5)

Ao chamar o método receive_messages você pode, opcionalmente, especificar um valor para max_messages, que é o número de mensagens a serem resgatadas da fila de espera. O padrão é 1 mensagem e o máximo são 32 mensagens. Você também pode especificar um valor para o visibility_timeout, o que ocultará as mensagens de outras operações durante o período do tempo limite. O padrão é 30 segundos.

Excluir mensagens de uma fila

Exclua mensagens da fila depois que elas forem recebidas e processadas. Nesse caso, o processamento só exibe a mensagem no console.

O aplicativo pausa a entrada do usuário chamando input antes de processar e excluir as mensagens. Verifique no portal do Azure se os recursos foram criados corretamente antes de serem excluídos. As mensagens que não forem explicitamente excluídas acabarão se tornando novamente visíveis na fila de espera para obterem mais uma chance de processamento.

Adicione este código ao final do bloco try:

    print("\nPress Enter key to 'process' messages and delete them from the queue...")
    input()

    for msg_batch in messages.by_page():
            for msg in msg_batch:
                # "Process" the message
                print(msg.content)
                # Let the service know we're finished with
                # the message and it can be safely deleted.
                queue_client.delete_message(msg)

Excluir uma fila

O código a seguir limpa os recursos que o aplicativo criou ao excluir a fila usando o método delete_queue.

Adicione este código ao final do bloco try e salve o arquivo:

    print("\nPress Enter key to delete the queue...")
    input()

    # Clean up
    print("Deleting queue...")
    queue_client.delete_queue()

    print("Done")

Executar o código

Esse aplicativo cria e adiciona três mensagens a uma fila do Azure. O código lista as mensagens na fila e, em seguida, recupera essas mensagens e as exclui, antes de excluir a fila.

Na janela do seu console, navegue até o diretório que contém o arquivo queues-quickstart.py e use o comando python abaixo para executar o aplicativo.

python queues-quickstart.py

A saída do aplicativo é semelhante ao seguinte exemplo:

Azure Queue Storage client library - Python quickstart sample
Creating queue: quickstartqueues-<UUID>

Adding messages to the queue...

Peek at the messages in the queue...
Message: First message
Message: Second message
Message: Third message

Updating the third message in the queue...

Receiving messages from the queue...

Press Enter key to 'process' messages and delete them from the queue...

First message
Second message
Third message has been updated

Press Enter key to delete the queue...

Deleting queue...
Done

Quando o aplicativo pausar antes de receber mensagens, verifique sua conta de armazenamento no portal do Azure. Verifique se as mensagens estão na fila.

Pressione a tecla Enter para receber e excluir as mensagens. Quando solicitado, pressione a tecla Enter novamente para excluir a fila e concluir a demonstração.

Próximas etapas

Neste início rápido, você aprendeu a criar uma fila e a adicionar mensagens a ela usando código Python. Em seguida, você aprendeu a espiar, recuperar e excluir mensagens. Por fim, você aprendeu a excluir uma fila de mensagens.

Para obter tutoriais, amostras, inícios rápidos e outros tipos de documentação, visite:

• 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.
• Para saber mais, confira as bibliotecas do Armazenamento do Azure para Python.
• Para obter mais aplicativos de exemplo do Armazenamento de Filas do Azure, confira Biblioteca de clientes do Armazenamento de Filas do Azure para Python – exemplos.