Biblioteca de cliente de Filas de Armazenamento do Azure para Python – versão 12.9.0

Artigo
12/05/2023

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 única mensagem de fila pode ter até 64 KiB de tamanho e uma fila pode conter milhões de mensagens, até ao limite total de capacidade de uma conta de armazenamento.

Utilizações comuns do Armazenamento de filas:

Criação de um registo de tarefas pendentes do trabalho para processamento de forma assíncrona
Transmitir mensagens entre diferentes partes de uma aplicação distribuída

Introdução

Pré-requisitos

O Python 3.7 ou posterior é necessário para utilizar este pacote. Para obter mais detalhes, leia a nossa página sobre a política de suporte de versões do Azure SDK para Python.
Tem de ter uma subscrição do Azure e uma conta de armazenamento do Azure para utilizar este pacote.

Instalar o pacote

Instale a biblioteca de cliente das Filas de Armazenamento do Azure para Python com pip:

pip install azure-storage-queue

Criar uma conta de armazenamento

Se quiser criar uma nova conta de armazenamento, pode utilizar o Portal do Azure, o Azure PowerShell ou a CLI do Azure:

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

Criar o cliente

A biblioteca de cliente de Filas de Armazenamento do Azure para Python permite-lhe interagir com três tipos de recursos: a própria conta de armazenamento, filas e mensagens. A interação com estes recursos começa com uma instância de um cliente. Para criar um objeto de cliente, precisará do URL do ponto final de serviço de fila da conta de armazenamento e de uma credencial que lhe permita aceder à conta de armazenamento:

from azure.storage.queue import QueueServiceClient

service = QueueServiceClient(account_url="https://<my-storage-account-name>.queue.core.windows.net/", credential=credential)

Procurar o URL da conta

Pode encontrar o URL do serviço de fila da conta de armazenamento com o portal do Azure, o Azure PowerShell ou a CLI do Azure:

# Get the queue service URL for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.queue"

Tipos de credenciais

O credential parâmetro pode ser fornecido em várias formas diferentes, consoante o tipo de autorização que pretende utilizar:

Para utilizar um token de assinatura de acesso partilhado (SAS), forneça o token como uma cadeia. Se o URL da conta incluir o token de SAS, omita o parâmetro de credencial. Pode gerar um token de SAS a partir do Portal do Azure em "Assinatura de acesso partilhado" ou utilizar uma das generate_sas() funções para criar um token sas para a conta de armazenamento ou fila:

from datetime import datetime, timedelta
from azure.storage.queue import QueueServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    start=datetime.utcnow(),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

queue_service_client = QueueServiceClient(account_url="https://<my_account_name>.queue.core.windows.net", credential=sas_token)

Para utilizar uma chave partilhada da conta de armazenamento (também conhecida como chave de conta ou chave de acesso), forneça a chave como uma cadeia. Isto pode ser encontrado no Portal do Azure na secção "Chaves de Acesso" ou ao executar o seguinte comando da CLI do Azure:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Utilize a chave como o parâmetro de credencial para autenticar o cliente:
```
from azure.storage.queue import QueueServiceClient
service = QueueServiceClient(account_url="https://<my_account_name>.queue.core.windows.net", credential="<account_access_key>")
```
Para utilizar uma credencial de token do Azure Active Directory (AAD), forneça uma instância do tipo de credencial pretendido obtido a partir da biblioteca de identidades do azure . Por exemplo, DefaultAzureCredential pode ser utilizado para autenticar o cliente.

Isto requer alguma configuração inicial:
- Instalar azure-identity
- Registar uma nova aplicação do AAD e dar permissões para aceder ao Armazenamento do Azure
- Conceder acesso aos dados da Fila do Azure com o RBAC no portal do Azure
- Defina os valores do ID de cliente, do ID do inquilino e do segredo do cliente da aplicação do AAD como variáveis de ambiente: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET
Utilize a credencial do token devolvido para autenticar o cliente:
```
    from azure.identity import DefaultAzureCredential
    from azure.storage.queue import QueueServiceClient
    token_credential = DefaultAzureCredential()

    queue_service_client = QueueServiceClient(
        account_url="https://<my_account_name>.queue.core.windows.net",
        credential=token_credential
    )
```

Criar o cliente a partir de um cadeia de ligação

Consoante o seu caso de utilização e o método de autorização, pode preferir inicializar uma instância de cliente com um cadeia de ligação de armazenamento em vez de fornecer o URL e a credencial da conta separadamente. Para tal, transmita o cadeia de ligação de armazenamento para o método de classe do from_connection_string cliente:

from azure.storage.queue import QueueServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = QueueServiceClient.from_connection_string(conn_str=connection_string)

O cadeia de ligação para a sua conta de armazenamento pode ser encontrado no Portal do Azure na secção "Chaves de Acesso" ou ao executar o seguinte comando da CLI:

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

Conceitos-chave

Os seguintes componentes compõem o Serviço de Filas do Azure:

A própria conta de armazenamento
Uma fila na conta de armazenamento, que contém um conjunto de mensagens
Uma mensagem dentro de uma fila, em qualquer formato, de até 64 KiB

A biblioteca de cliente das Filas de Armazenamento do Azure para Python permite-lhe interagir com cada um destes componentes através da utilização de um objeto de cliente dedicado.

Clientes Assíncrono

Esta biblioteca inclui uma API assíncrona completa suportada no Python 3.5 e superior. Para utilizá-lo, primeiro tem de instalar um transporte assíncrono, como o aiohttp. Veja a documentação do azure-core para obter mais informações.

Os clientes assíncrono e as credenciais devem ser fechados quando já não forem necessários. Estes objetos são gestores de contexto assíncrono e definem métodos assíncronos close .

Clientes

São fornecidos dois clientes diferentes para interagir com os vários componentes do Serviço de Fila:

QueueServiceClient – este cliente representa a interação com a própria conta de armazenamento do Azure e permite-lhe adquirir instâncias de cliente pré-configuradas para aceder às filas no mesmo. Fornece operações para obter e configurar as propriedades da conta, bem como listar, criar e eliminar filas na conta. Para realizar operações numa fila específica, obtenha um cliente com o get_queue_client método .
QueueClient – este cliente representa a interação com uma fila específica (que ainda não precisa de existir). Fornece operações para criar, eliminar ou configurar uma fila e inclui operações para enviar, receber, pré-visualizar, eliminar e atualizar mensagens dentro da mesma.

Mensagens

Enviar – adiciona uma mensagem à fila e, opcionalmente, define um tempo limite de visibilidade para a mensagem.
Receber – obtém uma mensagem da fila e torna-a invisível para outros consumidores.
Pré-visualizar – obtém uma mensagem a partir da frente da fila, sem alterar a visibilidade da mensagem.
Atualização - Atualizações o tempo limite de visibilidade de uma mensagem e/ou o conteúdo da mensagem.
Eliminar – elimina uma mensagem especificada da fila.
Limpar – limpa todas as mensagens da fila.

Exemplos

As secções seguintes fornecem vários fragmentos de código que abrangem algumas das tarefas mais comuns da Fila de Armazenamento, incluindo:

Criar uma fila
Enviar mensagens
A receber mensagens

Criar uma fila

Criar uma fila na sua conta de armazenamento

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
queue.create_queue()

Utilizar o cliente assíncrono para criar uma fila

from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
await queue.create_queue()

Enviar mensagens

Enviar mensagens para a sua fila

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
queue.send_message("I'm using queues!")
queue.send_message("This is my second message")

Enviar mensagens de forma assíncrona

import asyncio
from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
await asyncio.gather(
    queue.send_message("I'm using queues!"),
    queue.send_message("This is my second message")
)

A receber mensagens

Receber e processar mensagens da sua fila

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
response = queue.receive_messages()

for message in response:
    print(message.content)
    queue.delete_message(message)

# Printed messages from the front of the queue:
# >> I'm using queues!
# >> This is my second message

Receber e processar mensagens em lotes

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
response = queue.receive_messages(messages_per_page=10)

for message_batch in response.by_page():
    for message in message_batch:
        print(message.content)
        queue.delete_message(message)

Receber e processar mensagens de forma assíncrona

from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
response = queue.receive_messages()

async for message in response:
    print(message.content)
    await queue.delete_message(message)

Configuração opcional

Argumentos de palavra-chave opcionais que podem ser transmitidos ao nível do cliente e por operação.

Configuração da Política de Repetição

Utilize os seguintes argumentos de palavra-chave ao instanciar um cliente para configurar a política de repetição:

retry_total (int): número total de tentativas a permitir. Tem precedência sobre outras contagens. retry_total=0 Transmita se não quiser repetir os pedidos. A predefinição é 10.
retry_connect (int): quantos erros relacionados com a ligação deve repetir. A predefinição é 3.
retry_read (int): quantas vezes repetir erros de leitura. A predefinição é 3.
retry_status (int): quantas vezes tentar novamente códigos de estado incorretos. A predefinição é 3.
retry_to_secondary (bool): se o pedido deve ser repetido para secundário, se possível. Esta ação só deve ser ativada para as contas RA-GRS e podem ser processados dados potencialmente obsoletos. Predefinições para False.

Outra configuração de cliente/por operação

Outros argumentos de palavra-chave de configuração opcionais que podem ser especificados no cliente ou por operação.

Argumentos de palavra-chave do cliente:

connection_timeout (int): o número de segundos que o cliente aguardará para estabelecer uma ligação ao servidor. A predefinição é de 20 segundos.
read_timeout (int): o número de segundos que o cliente aguardará, entre operações de leitura consecutivas, para obter uma resposta do servidor. Trata-se de um tempo limite ao nível do socket e não é afetado pelo tamanho geral dos dados. Os tempos limite de leitura do lado do cliente serão repetidos automaticamente. A predefinição é de 60 segundos.
transporte (Qualquer): transporte fornecido pelo utilizador para enviar o pedido HTTP.

Argumentos de palavra-chave por operação:

raw_response_hook (callable): a chamada de retorno dada utiliza a resposta devolvida pelo serviço.
raw_request_hook (callable): a chamada de retorno especificada utiliza o pedido antes de ser enviado para o serviço.
client_request_id (str): identificação especificada pelo utilizador opcional do pedido.
user_agent (str): acrescenta o valor personalizado ao cabeçalho user-agent a ser enviado com o pedido.
logging_enable (bool): ativa o registo ao nível de DEBUG. Predefinições para Falso. Também pode ser transmitido ao nível do cliente para ativá-lo para todos os pedidos.
logging_body (bool): ativa o registo do pedido e do corpo da resposta. Predefinições para Falso. Também pode ser transmitido ao nível do cliente para ativá-lo para todos os pedidos.
cabeçalhos (dict): transmita cabeçalhos personalizados como chave, pares de valores. Por exemplo, headers={'CustomValue': value}

Resolução de problemas

Geral

Os clientes da Fila de Armazenamento geram exceções definidas no Azure Core.

Esta lista pode ser utilizada para referência para obter exceções geradas. Para obter o código de erro específico da exceção, utilize o error_code atributo, ou seja, exception.error_code.

Registo

Esta biblioteca utiliza a biblioteca de registos padrão para registos. As informações básicas sobre as sessões HTTP (URLs, cabeçalhos, etc.) são registadas ao nível da INFORMAÇÃO.

O registo ao nível de DEBUG detalhado, incluindo corpos de pedido/resposta e cabeçalhos não retotados, pode ser ativado num cliente com o logging_enable argumento:

import sys
import logging
from azure.storage.queue import QueueServiceClient

# Create a logger for the 'azure.storage.queue' SDK
logger = logging.getLogger('azure.storage.queue')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = QueueServiceClient.from_connection_string("your_connection_string", logging_enable=True)

Da mesma forma, logging_enable pode ativar o registo detalhado para uma única operação, mesmo quando não está ativado para o cliente:

service_client.get_service_stats(logging_enable=True)

Passos seguintes

Mais código de exemplo

Introdução aos nossos exemplos de Fila.

Estão disponíveis vários exemplos do SDK Python de Filas de Armazenamento no repositório do GitHub do SDK. Estes exemplos fornecem código de exemplo para cenários adicionais normalmente encontrados ao trabalhar com Filas de Armazenamento:

queue_samples_hello_world.py (versão assíncrona) - Exemplos encontrados neste artigo:
- Criação de cliente
- Criar uma fila
- Enviar mensagens
- Receber mensagens
queue_samples_authentication.py (versão assíncrona) – Exemplos para autenticar e criar o cliente:
- A partir de um cadeia de ligação
- A partir de uma chave de acesso partilhado
- A partir de um token de assinatura de acesso partilhado
- A partir do Azure Active Directory
queue_samples_service.py (versão assíncrona) – Exemplos para interagir com o serviço de fila:
- Obter e definir propriedades do serviço
- Listar filas numa conta de armazenamento
- Criar e eliminar uma fila do serviço
- Obter o QueueClient
queue_samples_message.py (versão assíncrona) – Exemplos para trabalhar com filas e mensagens:
- Definir uma política de acesso
- Obter e definir metadados de fila
- Enviar e receber mensagens
- Eliminar mensagens especificadas e limpar todas as mensagens
- Pré-visualizar e atualizar mensagens

Documentação adicional

Para obter documentação mais extensa sobre o armazenamento de Filas do Azure, veja a documentação do Armazenamento de Filas do Azure sobre docs.microsoft.com.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou o contacto opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.