Compartilhar via

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

Comece com a biblioteca de clientes do Azure Queue Storage para Python. O Armazenamento de Filas do Azure é um serviço para armazenar um grande número 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 | Código-fonte da biblioteca | Pacote (Índice de Pacote do Python) | Amostras

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 comprimento da fila
  • Receber mensagens de uma fila
  • Excluir mensagens de uma fila
  • Excluir uma fila

Pré-requisitos

Configurando

Esta seção orienta você na preparação de um projeto para trabalhar 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 do console (como cmd, PowerShell ou Bash), crie um novo diretório para o projeto.

    mkdir queues-quickstart

  2. Alterne para o diretório recém-criado queues-quickstart.

    cd queues-quickstart

Instalar os pacotes

No diretório do projeto, instale o pacote da biblioteca cliente do Armazenamento de Filas do Azure para Python usando o comando pip install. O pacote de identidade do azure é 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. Adicionar import declarações

  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 de aplicativo para a maioria dos serviços do Azure devem ser autorizadas. Usar a DefaultAzureCredential classe fornecida pela biblioteca de clientes da Identidade do Azure é a abordagem recomendada para implementar conexões sem senha com os serviços do Azure em seu código.

Você também pode autorizar solicitações aos serviços do Azure usando senhas, cadeias de conexão ou outras credenciais diretamente. No entanto, essa abordagem deve ser usada com cuidado. 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 da conta para permitir a autenticação sem senha. Ambas as opções são demonstradas no exemplo a seguir.

DefaultAzureCredential é uma classe fornecida pela biblioteca de clientes da Identidade do Azure para Python. Para saber mais sobre DefaultAzureCredential, confira a visão geral de DefaultAzureCredential. DefaultAzureCredential dá suporte a vários métodos de autenticação e determina qual método deve ser usado em runtime. Essa abordagem permite que seu aplicativo use diferentes métodos de autenticação em ambientes diferentes (local versus produção) sem implementar código específico do ambiente.

Por exemplo, seu aplicativo pode se autenticar usando suas credenciais de entrada do Visual Studio Code ao desenvolver localmente e, em seguida, usar uma identidade gerenciada depois que ele tiver sido implantado no Azure. Nenhuma alteração de código é necessária para essa transição.

Ao desenvolver localmente, verifique se a conta de usuário que está acessando os dados da fila tem as permissões corretas. Para ler e gravar dados da fila, você precisará do Colaborador de Dados da Fila de Armazenamento. Para atribuir essa função a si mesmo, você precisará receber a atribuição da função Administrador de Acesso do Usuário ou de outra função que inclua a ação Microsoft.Authorization/roleAssignments/write. É possível atribuir funções RBAC do Azure a um usuário usando o portal do Azure, a CLI do Azure ou o Azure PowerShell. Você pode saber mais sobre os escopos disponíveis para atribuições de função na página de visão geral do escopo.

Nesse cenário, você atribuirá permissões à sua conta de usuário, com escopo para a conta de armazenamento, para seguir o Princípio do Privilégio Mínimo. Essa prática fornece aos usuários apenas as permissões mínimas necessárias e cria ambientes de produção mais seguros.

O exemplo a seguir atribuirá a função Colaborador de Dados da Fila de Armazenamento à sua conta de usuário, que fornece acesso de leitura e gravação aos dados da fila em sua conta de armazenamento.

Importante

Na maioria dos casos, levará um ou dois minutos para a atribuição de função se propagar no Azure, mas em casos raros pode levar até oito minutos. Se você receber erros de autenticação ao executar o código pela primeira vez, aguarde alguns instantes e tente novamente.

  1. No portal do Azure, localize sua conta de armazenamento usando a barra de pesquisa principal ou a navegação à esquerda.

  2. Na página de visão geral da conta de armazenamento, selecione Controle de acesso (IAM) no menu à esquerda.

  3. Na página Controle de acesso (IAM), selecione a guia Atribuições de função.

  4. Selecione + Adicionar no menu superior e, em seguida, Adicionar atribuição de função no menu suspenso resultante.

Uma captura de tela mostrando como atribuir uma função.

  1. Use a caixa de pesquisa para filtrar os resultados para a função desejada. Para este exemplo, pesquise o Colaborador de dados da fila de armazenamento, e selecione o resultado correspondente e, em seguida, escolha Avançar.

  2. Em Atribuir acesso a, selecione Usuário, grupo ou entidade de serviço e, em seguida, escolha + Selecionar membros.

  3. No diálogo, pesquise seu nome de usuário do Microsoft Entra (geralmente, seu endereço de email usuário@domínio) e escolha Selecionar na parte inferior do diálogo.

  4. Selecione Revisar + atribuir para ir para a página final e, em seguida, Revisar + atribuir novamente para concluir o processo.

Modelo de objeto

O Armazenamento de Filas do Azure é um serviço para armazenar um grande número de mensagens. Uma mensagem de fila pode ter até 64 KB de tamanho. Uma fila pode conter milhões de mensagens, até o limite total de capacidade de uma conta de armazenamento. "Filas são comumente usadas para criar uma lista de tarefas para processar de forma assíncrona." 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 obter mais informações sobre contas de armazenamento, consulte a 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 todo em letras minúsculas. Para obter informações sobre filas de nomenclatura, consulte Filas de Nomenclatura e Metadados.
  • Mensagem: uma mensagem, em qualquer formato, de até 64 KB. Uma mensagem pode permanecer na fila por no máximo 7 dias. Para a versão 2017-07-29 ou posterior, o tempo máximo de vida útil 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.

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

Diagrama da arquitetura de armazenamento de filas

Use as seguintes classes python para interagir com esses recursos:

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

Exemplos de código

Estes 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 o acesso e criar um objeto cliente

Verifique se você está autenticado com a mesma conta do Microsoft Entra à qual atribuiu a função. Você pode autenticar por meio da CLI do Azure, do Visual Studio Code ou do Azure PowerShell.

Entre no Azure por meio da CLI do Azure usando o seguinte comando:

az login

Depois de autenticado, você pode criar e autorizar um QueueClient objeto usando DefaultAzureCredential para acessar dados de fila na conta de armazenamento. DefaultAzureCredential descobre e usa automaticamente a conta com a qual você entrou na etapa anterior.

Para autorizar com DefaultAzureCredential, verifique se você adicionou o pacote azure-identity, conforme descrito em Instalar os Pacotes. Além disso, adicione a seguinte instrução de importação no arquivo queues-quickstart.py :

from azure.identity import DefaultAzureCredential

Decida um nome para a fila e crie uma instância da QueueClient classe, usando DefaultAzureCredential para autorização. Usamos esse objeto cliente para criar e interagir com o recurso de fila na conta de armazenamento.

Importante

Os nomes de fila podem conter apenas letras minúsculas, números e hifens e devem começar com uma letra ou um número. Cada hífen deve ser precedido e seguido por um caractere não hifen. O nome também deve ter entre 3 e 63 caracteres. Para obter mais informações sobre filas de nomenclatura, consulte Nomenclatura de filas e metadados.

Adicione o seguinte código no bloco try e certifique-se de substituir o valor do espaço reservado <storage-account-name>.

    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)

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

Você pode configurar 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()
                        )

Criar uma fila

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

Adicione este código ao final do try bloco:

    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 send_message método. 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 try bloco:

    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

Visualize as mensagens na fila chamando o método peek_messages. Esse método recupera uma ou mais mensagens da frente da fila, mas não altera a visibilidade da mensagem.

Adicione este código ao final do try bloco:

    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 update_message método. Esse método pode alterar o tempo limite e o conteúdo da visibilidade de uma mensagem. O conteúdo da mensagem deve ser uma cadeia de caracteres codificada em UTF-8 com até 64 KB de tamanho. Junto com o novo conteúdo, transmita os valores da mensagem que foi salva anteriormente no código. Os saved_message valores identificam qual mensagem atualizar.

    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 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 .approximate_message_count

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

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

Receber mensagens de uma fila

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

Adicione este código ao final do try bloco:

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

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

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

Excluir mensagens de uma fila

Exclua mensagens da fila depois de serem recebidas e processadas. Nesse caso, o processamento está apenas exibindo a mensagem no console.

O aplicativo pausa para receber 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. Todas as mensagens não excluídas explicitamente eventualmente ficam visíveis na fila novamente para outra chance de processá-las.

Adicione este código ao final do try bloco:

    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 excluindo a fila usando o delete_queue método.

Adicione este código ao final do try bloco 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, as recupera e as exclui antes de finalmente excluir a fila.

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

python queues-quickstart.py

A saída do aplicativo é semelhante ao exemplo a seguir:

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 pausa antes de receber mensagens, verifique sua conta de armazenamento no portal do Azure. Verifique se as mensagens estão na fila.

Pressione a Enter tecla para receber e excluir as mensagens. Quando solicitado, pressione a Enter tecla 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 adicionar mensagens a ela usando o código Python. Em seguida, você aprendeu a espiar, recuperar e excluir mensagens. Por fim, você aprendeu a excluir uma fila de mensagens.

Para tutoriais, exemplos, inícios rápidos e outras documentações, visite:

Azure para desenvolvedores do Python

  • Last updated on