Biblioteca de clientes das 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 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 KiB de tamanho e uma fila pode conter milhões de mensagens, até o limite total de capacidade de uma conta de armazenamento.

Usos comuns de Armazenamento de filas incluem:

Criar uma lista de pendências de trabalho para processar de maneira assíncrona
Passando mensagens entre diferentes partes de um aplicativo distribuído

Introdução

Pré-requisitos

É necessário ter o Python 3.7 ou posterior para usar esse pacote. Para obter mais detalhes, leia nossa página na política de suporte do SDK do Azure para Python.
Você deve ter uma assinatura do Azure e uma conta de armazenamento do Azure para usar esse pacote.

Instalar o pacote

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

pip install azure-storage-queue

Criar uma conta de armazenamento

Se você quiser criar uma nova conta de armazenamento, poderá usar o Portal do Azure, 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

Crie o cliente

A biblioteca de clientes das Filas de Armazenamento do Azure para Python permite que você interaja com três tipos de recursos: a própria conta de armazenamento, filas e mensagens. A interação com esses recursos começa com uma instância de um cliente. Para criar um objeto cliente, você precisará da URL do ponto de extremidade do serviço de fila da conta de armazenamento e de uma credencial que permita acessar a conta de armazenamento:

from azure.storage.queue import QueueServiceClient

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

Pesquisando a URL da conta

Você pode encontrar a URL do serviço de fila da conta de armazenamento usando o Portal do Azure, 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, dependendo do tipo de autorização que você deseja usar:

Para usar um token SAS (assinatura de acesso compartilhado), forneça o token como uma cadeia de caracteres. Se a URL da conta incluir o token SAS, omita o parâmetro de credencial. Você pode gerar um token SAS do Portal do Azure em "Assinatura de acesso compartilhado" ou usar 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 usar uma chave compartilhada da conta de armazenamento (também conhecida como chave de conta ou chave de acesso), forneça a chave como uma cadeia de caracteres. Isso pode ser encontrado no Portal do Azure na seção "Chaves de Acesso" ou executando o seguinte comando da CLI do Azure:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Use 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 usar uma credencial de token do AAD (Azure Active Directory), forneça uma instância do tipo de credencial desejado obtido da biblioteca azure-identity . Por exemplo, DefaultAzureCredential pode ser usado para autenticar o cliente.

Isso requer alguma configuração inicial:
- Instalar azure-identity
- Registrar um novo aplicativo do AAD e conceder permissões para acessar o Armazenamento do Azure
- Conceder acesso aos dados da Fila do Azure com o RBAC no Portal do Azure
- Defina os valores da ID do cliente, da ID do locatário e do segredo do cliente do aplicativo AAD como variáveis de ambiente: AZURE_TENANT_ID, AZURE_CLIENT_ID AZURE_CLIENT_SECRET
Use a credencial de token retornada 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
    )
```

Criando o cliente de um cadeia de conexão

Dependendo do caso de uso e do método de autorização, talvez você prefira inicializar uma instância de cliente com uma cadeia de conexão de armazenamento em vez de fornecer a URL da conta e a credencial separadamente. Para fazer isso, passe o cadeia de conexã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)

A cadeia de conexão com sua conta de armazenamento pode ser encontrada no Portal do Azure na seção "Chaves de Acesso" ou executando o seguinte comando da CLI:

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

Principais conceitos

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

A própria conta de armazenamento
Uma fila dentro da 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 clientes das Filas de Armazenamento do Azure para Python permite que você interaja com cada um desses componentes por meio do uso de um objeto cliente dedicado.

Clientes assíncronos

Essa biblioteca inclui uma API assíncrona completa com suporte no Python 3.5+. Para usá-lo, primeiro você deve instalar um transporte assíncrono, como aiohttp. Confira a documentação do azure-core para obter mais informações.

Clientes e credenciais assíncronos devem ser fechados quando não forem mais necessários. Esses objetos são gerenciadores de contexto assíncronos e definem métodos assíncronos close .

Clientes

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

QueueServiceClient – esse cliente representa a interação com a própria conta de armazenamento do Azure e permite que você adquira instâncias de cliente pré-configuradas para acessar as filas internas. Ele fornece operações para recuperar e configurar as propriedades da conta, bem como listar, criar e excluir filas dentro da conta. Para executar operações em uma fila específica, recupere um cliente usando o get_queue_client método .
QueueClient – esse cliente representa a interação com uma fila específica (que ainda não precisa existir). Ele fornece operações para criar, excluir ou configurar uma fila e inclui operações para enviar, receber, espiar, excluir e atualizar mensagens dentro dela.

Mensagens

Enviar – adiciona uma mensagem à fila e, opcionalmente, define um tempo limite de visibilidade para a mensagem.
Receber – recupera uma mensagem da fila e a torna invisível para outros consumidores.
Espiar – recupera uma mensagem da frente da fila, sem alterar a visibilidade da mensagem.
Atualização – Atualizações o tempo limite de visibilidade de uma mensagem e/ou do conteúdo da mensagem.
Excluir – exclui uma mensagem especificada da fila.
Limpar – limpa todas as mensagens da fila.

Exemplos

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas mais comuns da Fila de Armazenamento, incluindo:

Criando uma fila
Enviar mensagens
Recebendo mensagens

Como criar uma fila

Criar uma fila em 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()

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

Envio de mensagens

Enviar mensagens para 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")
)

Recebendo mensagens

Receber e processar mensagens da 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 opcionais palavra-chave que podem ser passados no nível do cliente e por operação.

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

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

retry_total (int): número total de tentativas a serem permitidas. Tem precedência sobre outras contagens. retry_total=0 Passe se você não quiser repetir as solicitações. O valor padrão é 10.
retry_connect (int): quantos erros relacionados à conexão tentar novamente. O valor padrão é 3.
retry_read (int): quantas vezes tentar novamente em erros de leitura. O valor padrão é 3.
retry_status (int): quantas vezes tentar novamente em códigos de status inválidos. O valor padrão é 3.
retry_to_secondary (bool): se a solicitação deve ser repetida para secundária, se possível. Isso só deve ser habilitado para que contas RA-GRS sejam usadas e dados potencialmente obsoletos possam ser tratados. Assume o padrão de False.

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

Outra configuração opcional palavra-chave argumentos 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 conexão com o servidor. O padrão é 20 segundos.
read_timeout (int): o número de segundos que o cliente aguardará, entre operações de leitura consecutivas, por uma resposta do servidor. Esse é um tempo limite de nível de soquete e não é afetado pelo tamanho geral dos dados. Os tempos limite de leitura do lado do cliente serão repetidos automaticamente. O padrão é 60 segundos.
transport (Any): transporte fornecido pelo usuário para enviar a solicitação HTTP.

Argumentos de palavra-chave por operação:

raw_response_hook (callable): o retorno de chamada especificado usa a resposta retornada do serviço.
raw_request_hook (callable): o retorno de chamada especificado usa a solicitação antes de ser enviado ao serviço.
client_request_id (str): identificação especificada pelo usuário opcional da solicitação.
user_agent (str): acrescenta o valor personalizado ao cabeçalho user-agent a ser enviado com a solicitação.
logging_enable (bool): habilita o registro em log no nível de DEBUG. Usa False como padrão. Também pode ser passado no nível do cliente para habilitá-lo para todas as solicitações.
logging_body (bool): habilita o registro em log do corpo da solicitação e da resposta. Usa False como padrão. Também pode ser passado no nível do cliente para habilitá-lo para todas as solicitações.
cabeçalhos (ditado): passe cabeçalhos personalizados como pares de chave e valor. Por exemplo, headers={'CustomValue': value}

Solução de problemas

Geral

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

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

Registro em log

Essa biblioteca usa a biblioteca de log padrão para registro em log. Informações básicas sobre sessões HTTP (URLs, cabeçalhos etc.) são registradas no nível INFO.

O log detalhado do nível de DEBUG, incluindo corpos de solicitação/resposta e cabeçalhos não redigidos, pode ser habilitado em um 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 habilitar o log detalhado para uma operação individual, mesmo quando ela não está habilitada para o cliente:

service_client.get_service_stats(logging_enable=True)

Próximas etapas

Mais códigos de exemplo

Introdução aos nossos exemplos de fila.

Várias filas de armazenamento Os exemplos do SDK do Python estão disponíveis para você no repositório GitHub do SDK. Esses exemplos fornecem código de exemplo para cenários adicionais comumente 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:
- De um cadeia de conexão
- De uma chave de acesso compartilhada
- De um token de assinatura de acesso compartilhado
- 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 de serviço
- Listar filas em uma conta de armazenamento
- Criar e excluir 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
- Excluir mensagens especificadas e limpar todas as mensagens
- Espiar e atualizar mensagens

Documentação adicional

Para obter uma documentação mais abrangente sobre o armazenamento de Filas do Azure, consulte a documentação do Armazenamento de Filas do Azure no docs.microsoft.com.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.