Compartir a través de

Biblioteca cliente de colas de Azure Storage para Python, versión 12.9.0

  • Artículo

El almacenamiento en cola de Azure es un servicio para almacenar grandes cantidades de mensajes a los que puede obtenerse acceso desde cualquier lugar del mundo a través de llamadas autenticadas con HTTP o HTTPS. Un único mensaje de cola puede tener un tamaño de hasta 64 KiB y una cola puede contener millones de mensajes, hasta el límite de capacidad total de una cuenta de almacenamiento.

El almacenamiento en cola suele usarse para realizar las siguientes tareas:

  • Creación de trabajo pendiente para el procesamiento asincrónico
  • Pasar mensajes entre diferentes partes de una aplicación distribuida

Código | fuentePaquete (PyPI) | Paquete (Conda) | Documentación | de referencia de API | Documentación del productoMuestras

Introducción

Requisitos previos

Instalar el paquete

Instale la biblioteca cliente de Colas de Azure Storage para Python con pip:

pip install azure-storage-queue

Crear una cuenta de almacenamiento

Si desea crear una cuenta de almacenamiento, puede usar Azure Portal, Azure PowerShell o la CLI de 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

Creación del cliente

La biblioteca cliente de Colas de Azure Storage para Python permite interactuar con tres tipos de recursos: la propia cuenta de almacenamiento, las colas y los mensajes. La interacción con estos recursos comienza con una instancia de un cliente. Para crear un objeto de cliente, necesitará la dirección URL del punto de conexión de queue service de la cuenta de almacenamiento y una credencial que le permita acceder a la cuenta de almacenamiento:

from azure.storage.queue import QueueServiceClient

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

Búsqueda de la dirección URL de la cuenta

Puede encontrar la dirección URL del servicio de cola de la cuenta de almacenamiento mediante Azure Portal, Azure PowerShell o la CLI de 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 credenciales

El credential parámetro se puede proporcionar en varias formas diferentes, según el tipo de autorización que desee usar:

  1. Para usar un token de firma de acceso compartido (SAS), proporcione el token como una cadena. Si la dirección URL de la cuenta incluye el token de SAS, omita el parámetro de credencial. Puede generar un token de SAS desde Azure Portal en "Firma de acceso compartido" o usar una de las generate_sas() funciones para crear un token sas para la cuenta de almacenamiento o la cola:

    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)

  2. Para usar una clave compartida de la cuenta de almacenamiento (también conocida como clave de cuenta o clave de acceso), proporcione la clave como una cadena. Esto se puede encontrar en Azure Portal en la sección "Claves de acceso" o mediante la ejecución del siguiente comando de la CLI de Azure:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    Use la clave como parámetro de credencial para autenticar el cliente:

    from azure.storage.queue import QueueServiceClient
service = QueueServiceClient(account_url="https://<my_account_name>.queue.core.windows.net", credential="<account_access_key>")

  3. Para usar una credencial de token de Azure Active Directory (AAD), proporcione una instancia del tipo de credencial deseado obtenido de la biblioteca azure-identity . Por ejemplo, DefaultAzureCredential se puede usar para autenticar el cliente.

    Esto requiere una configuración inicial:

    Use la credencial de token devuelta para autenticar al 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
    )

Creación del cliente a partir de un cadena de conexión

Según el caso de uso y el método de autorización, puede que prefiera inicializar una instancia de cliente con un cadena de conexión de almacenamiento en lugar de proporcionar la dirección URL de la cuenta y la credencial por separado. Para ello, pase el cadena de conexión de almacenamiento al método de clase del 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)

La cadena de conexión a la cuenta de almacenamiento se puede encontrar en Azure Portal en la sección "Claves de acceso" o mediante la ejecución del siguiente comando de la CLI:

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

Conceptos clave

Los siguientes componentes componen Azure Queue Service:

  • La propia cuenta de almacenamiento
  • Una cola dentro de la cuenta de almacenamiento, que contiene un conjunto de mensajes
  • Un mensaje dentro de una cola, en cualquier formato, de hasta 64 KiB

La biblioteca cliente de Colas de Azure Storage para Python permite interactuar con cada uno de estos componentes mediante el uso de un objeto de cliente dedicado.

Clientes asincrónicos

Esta biblioteca incluye una API asincrónica completa compatible con Python 3.5 y versiones posteriores. Para usarlo, primero debe instalar un transporte asincrónico, como aiohttp. Consulte la documentación de azure-core para más información.

Los clientes y credenciales asincrónicos deben cerrarse cuando ya no sean necesarios. Estos objetos son administradores de contexto asincrónicos y definen métodos asincrónicos close .

Clientes

Se proporcionan dos clientes diferentes para interactuar con los distintos componentes de Queue Service:

  1. QueueServiceClient : este cliente representa la interacción con la propia cuenta de almacenamiento de Azure y permite adquirir instancias de cliente preconfiguradas para acceder a las colas dentro. Proporciona operaciones para recuperar y configurar las propiedades de la cuenta, así como enumerar, crear y eliminar colas dentro de la cuenta. Para realizar operaciones en una cola específica, recupere un cliente mediante el get_queue_client método .
  2. QueueClient : este cliente representa la interacción con una cola específica (que aún no es necesario). Proporciona operaciones para crear, eliminar o configurar una cola e incluye operaciones para enviar, recibir, inspeccionar, eliminar y actualizar mensajes dentro de ella.

error de Hadoop

  • Enviar: agrega un mensaje a la cola y, opcionalmente, establece un tiempo de espera de visibilidad para el mensaje.
  • Receive: recupera un mensaje de la cola y hace que sea invisible para otros consumidores.
  • Vistazo: recupera un mensaje de la parte delantera de la cola, sin cambiar la visibilidad del mensaje.
  • Actualizar: Novedades el tiempo de espera de visibilidad de un mensaje o el contenido del mensaje.
  • Eliminar : elimina un mensaje especificado de la cola.
  • Borrar : borra todos los mensajes de la cola.

Ejemplos

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas más comunes de cola de Storage, entre las que se incluyen:

Creación de una cola

Creación de una cola en la cuenta de almacenamiento

from azure.storage.queue import QueueClient

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

Uso del cliente asincrónico para crear una cola

from azure.storage.queue.aio import QueueClient

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

Envío de mensajes

Envío de mensajes a la cola

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 mensajes de forma asincrónica

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

Recepción de mensajes

Recepción y procesamiento de mensajes de la cola

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

Recepción y procesamiento de mensajes en 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)

Recepción y procesamiento de mensajes de forma asincrónica

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)

Configuración opcional

Argumentos de palabra clave opcionales que se pueden pasar en el nivel de cliente y por operación.

Configuración de directiva de reintento

Use los argumentos de palabra clave siguientes al crear instancias de un cliente para configurar la directiva de reintento:

  • retry_total (int): número total de reintentos que se van a permitir. Tiene prioridad sobre otros recuentos. retry_total=0 Pase si no desea volver a intentarlo en las solicitudes. El valor predeterminado es 10.
  • retry_connect (int): cuántos errores relacionados con la conexión se reintentan. El valor predeterminado es 3.
  • retry_read (int): cuántas veces se reintenta en errores de lectura. El valor predeterminado es 3.
  • retry_status (int): cuántas veces se reintenta en códigos de estado incorrectos. El valor predeterminado es 3.
  • retry_to_secondary (bool): indica si la solicitud se debe reintentar a la secundaria, si es posible. Esto solo debe habilitarse en las cuentas de RA-GRS y se pueden controlar los datos potencialmente obsoletos. Tiene como valor predeterminado False.

Otra configuración de cliente o por operación

Otros argumentos de palabra clave de configuración opcionales que se pueden especificar en el cliente o por operación.

Argumentos de palabra clave de cliente:

  • connection_timeout (int): número de segundos que el cliente esperará para establecer una conexión con el servidor. El valor predeterminado es de 20 segundos.
  • read_timeout (int): número de segundos que el cliente esperará, entre operaciones de lectura consecutivas, para una respuesta del servidor. Se trata de un tiempo de espera de nivel de socket y no se ve afectado por el tamaño total de los datos. Los tiempos de espera de lectura del lado cliente se reintentarán automáticamente. El valor predeterminado es 60 segundos.
  • transport (Any): transporte proporcionado por el usuario para enviar la solicitud HTTP.

Argumentos de palabra clave por operación:

  • raw_response_hook (invocable): la devolución de llamada especificada usa la respuesta devuelta desde el servicio.
  • raw_request_hook (invocable): la devolución de llamada especificada usa la solicitud antes de enviarse al servicio.
  • client_request_id (str): el usuario opcional especificó la identificación de la solicitud.
  • user_agent (str): anexa el valor personalizado al encabezado user-agent que se enviará con la solicitud.
  • logging_enable (bool): habilita el registro en el nivel DEBUG. El valor predeterminado es False. También se puede pasar en el nivel de cliente para habilitarlo para todas las solicitudes.
  • logging_body (bool): habilita el registro del cuerpo de la solicitud y la respuesta. El valor predeterminado es False. También se puede pasar en el nivel de cliente para habilitarlo para todas las solicitudes.
  • encabezados (dict): pase encabezados personalizados como pares clave y valor. Por ejemplo headers={'CustomValue': value}

Solución de problemas

General

Los clientes de cola de Storage generan excepciones definidas en Azure Core.

Esta lista se puede usar como referencia para detectar excepciones iniciadas. Para obtener el código de error específico de la excepción, use el error_code atributo , es decir, exception.error_code.

Registro

Esta biblioteca usa la biblioteca de registro estándar para el registro. La información básica sobre las sesiones HTTP (direcciones URL, encabezados, etc.) se registra en el nivel INFO.

El registro detallado de nivel DEBUG, incluidos los cuerpos de solicitud/respuesta y los encabezados no aprobados, se puede habilitar en un cliente con el 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)

Igualmente, logging_enable puede habilitar el registro detallado de una sola operación, aunque no esté habilitado para el cliente:

service_client.get_service_stats(logging_enable=True)

Pasos siguientes

Más código de ejemplo

Empiece a trabajar con nuestros ejemplos de colas.

Hay disponibles varios ejemplos del SDK de Python de Colas de Storage en el repositorio de GitHub del SDK. Estos ejemplos proporcionan código de ejemplo para escenarios adicionales que se suelen encontrar al trabajar con colas de Storage:

  • queue_samples_hello_world.py (versión asincrónica): ejemplos que se encuentran en este artículo:

    • Creación de clientes
    • Creación de una cola
    • Envío de mensajes
    • Recepción de mensajes

  • queue_samples_authentication.py (versión asincrónica): ejemplos para autenticar y crear el cliente:

    • Desde un cadena de conexión
    • Desde una clave de acceso compartido
    • Desde un token de firma de acceso compartido
    • Desde Azure Active Directory

  • queue_samples_service.py (versión asincrónica): ejemplos para interactuar con el servicio de cola:

    • Obtención y establecimiento de las propiedades del servicio
    • Enumeración de colas en una cuenta de almacenamiento
    • Creación y eliminación de una cola del servicio
    • Obtención de QueueClient

  • queue_samples_message.py (versión asincrónica): ejemplos para trabajar con colas y mensajes:

    • Establecimiento de una directiva de acceso
    • Obtención y establecimiento de metadatos de cola
    • Envío y recepción de mensajes
    • Eliminar mensajes especificados y borrar todos los mensajes
    • Vistazo y actualizar mensajes

Documentación adicional

Para obtener documentación más amplia sobre Azure Queue Storage, consulte la documentación de Azure Queue Storage sobre docs.microsoft.com.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.