Compartir por

Inicio rápido: Biblioteca cliente de Azure Queue Storage para Python

  • Artigo

Introducción a la biblioteca cliente de Azure Queue Storage para Python. Azure Queue Storage es un servicio para almacenar gran cantidad de mensajes para su posterior recuperación y procesamiento. Siga estos pasos para instalar el paquete y probar el código de ejemplo para realizar tareas básicas.

Documentación de referencia de API | Código fuente de la biblioteca | Paquete (índice de paquetes de Python) | Ejemplos

Use la biblioteca cliente de Azure Queue Storage para Python para realizar las siguientes operaciones:

  • Creación de una cola
  • Adición de mensajes a una cola
  • Leer los mensajes de una cola
  • Eliminación de un mensaje de una cola
  • la longitud de la cola
  • mensajes de una cola
  • Eliminación de mensajes de una cola
  • Eliminación de una cola

Requisitos previos

Instalación

En esta sección se explica cómo preparar un proyecto para que funcione con la biblioteca cliente de Azure Queue Storage para Python.

Creación del proyecto

Cree una aplicación Python llamada queues-quickstart.

  1. En una ventana de la consola (como cmd, PowerShell o Bash), cree un directorio para el proyecto.

    mkdir queues-quickstart

  2. Cambie al directorio queues-quickstart recién creado.

    cd queues-quickstart

Instalación de los paquetes

Desde el directorio del proyecto, instale el paquete de la biblioteca cliente de Azure Queue Storage para Python mediante el comando pip install. El paquete azure-identity es necesario para las conexiones sin contraseña a los servicios de Azure.

pip install azure-storage-queue azure-identity

Instalación del marco de la aplicación

  1. Abra un nuevo archivo de texto en el editor de código.

  2. Agregue instrucciones import.

  3. Cree la estructura del programa, incluido un control de excepciones básico.

    Este es el código:

    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. Guarde el nuevo archivo como queues-quickstart.py en el directorio queues-quickstart.

Autentíquese en Azure

Deben autorizarse las solicitudes de aplicación a la mayor parte de servicios de Azure. El uso de la clase DefaultAzureCredential que proporciona la biblioteca cliente de Azure Identity es el enfoque recomendado para implementar conexiones sin contraseña a los servicios de Azure en el código.

También puede autorizar directamente las solicitudes a los servicios de Azure mediante contraseñas, cadenas de conexión u otras credenciales. Sin embargo, este enfoque debe usarse con precaución. Los desarrolladores deben ser meticulosos y no exponer nunca estos secretos en una ubicación que no sea segura. Cualquier persona que obtenga acceso a la contraseña o a la clave secreta puede autenticarse. DefaultAzureCredential ofrece ventajas de seguridad y administración mejoradas con respecto la clave de cuenta para permitir la autenticación sin contraseña. Ambas opciones se muestran en el ejemplo siguiente.

DefaultAzureCredential es una clase proporcionada por la biblioteca cliente de Azure Identity para Python. Para más información sobre DefaultAzureCredential, consulte la información general sobre DefaultAzureCredential. DefaultAzureCredential admite varios métodos de autenticación y determina el que se debe usar en tiempo de ejecución. Este enfoque permite que la aplicación use diferentes métodos de autenticación en distintos entornos (local frente a producción) sin implementar código específico del entorno.

Por ejemplo, la aplicación puede autenticarse con las credenciales de inicio de sesión de Visual Studio Code cuando se trabaja en un desarrollo localmente y, después, usar una identidad administrada tras haberse implementado en Azure. No se necesitan cambios de código para esta transición.

Al desarrollar localmente, asegúrese de que la cuenta de usuario que accede a los datos de la cola tenga los permisos correctos. Necesitará el Colaborador de datos de cola de almacenamiento para leer y escribir datos de la cola. Para asignarse este rol a sí mismo, necesitará que se le asigne el rol Administrador de acceso de usuario u otro rol que incluya la acción Microsoft.Authorization/roleAssignments/write. Puede asignar roles RBAC de Azure a un usuario mediante Azure Portal, la CLI de Azure o Azure PowerShell. Puede obtener más información sobre los ámbitos disponibles para las asignaciones de roles en la página de información general del ámbito.

En este escenario, asignará permisos a la cuenta de usuario, cuyo ámbito es la cuenta de almacenamiento, a fin de seguir el principio de privilegios mínimos. Esta práctica solo proporciona a los usuarios los permisos mínimos necesarios y crea entornos de producción más seguros.

En el ejemplo siguiente se asignará el rol Colaborador de datos de cola de almacenamiento a la cuenta de usuario, que proporciona acceso de lectura y escritura a los datos de la cola de la cuenta de almacenamiento.

Importante

En la mayoría de los casos, la asignación de roles tardará un minuto o dos en propagarse en Azure, pero en casos excepcionales puede tardar hasta ocho minutos. Si recibe errores de autenticación al ejecutar por primera vez el código, espere unos instantes e inténtelo de nuevo.

  1. En Azure Portal, busque la cuenta de almacenamiento mediante la barra de búsqueda principal o el panel de navegación de la izquierda.

  2. En la página de información general de la cuenta de almacenamiento, seleccione Control de acceso (IAM) en el menú de la izquierda.

  3. En la página Control de acceso (IAM), seleccione la pestaña Asignación de roles.

  4. Seleccione + Agregar en el menú superior y, a continuación, Agregar asignación de roles en el menú desplegable resultante.

A screenshot showing how to assign a role.

  1. Puede usar el cuadro de búsqueda para filtrar los resultados por el rol deseado. En este ejemplo, busque Colaborador de datos de cola de almacenamiento y seleccione el resultado coincidente y, a continuación, elija Siguiente.

  2. En la pestaña Asignar acceso a, seleccione Usuario, grupo o entidad de servicio y, a continuación, elija + Seleccionar miembros.

  3. En el cuadro de diálogo, busque el nombre de usuario de Microsoft Entra (normalmente su dirección de correo electrónico de user@domain) y, a continuación, elija Seleccionar en la parte inferior del cuadro de diálogo.

  4. Seleccione Revisar y asignar para ir a la página final y, a continuación, de nuevo Revisar y asignar para completar el proceso.

Modelo de objetos

Azure Queue Storage es un servicio para almacenar grandes cantidades de mensajes, Un mensaje de la cola puede llegar a tener hasta 64 KB. Una cola puede contener millones de mensajes, hasta el límite de capacidad total de una cuenta de almacenamiento. Las colas se utilizan normalmente para crear un trabajo pendiente del trabajo que se va a procesar de forma asincrónica. Queue Storage ofrece tres tipos de recursos:

  • Cuenta de almacenamiento:todo el acceso a Azure Storage se realiza a través de una cuenta de almacenamiento. Para más información sobre las cuentas de almacenamiento, consulte Introducción a las cuentas de Storage
  • Cola: una cola contiene un conjunto de mensajes. Todos los mensajes deben encontrarse en una cola. Tenga en cuenta que el nombre de la cola debe ir en minúsculas. Para más información, consulte Asignar nombres a colas y metadatos.
  • Mensaje: un mensaje, en cualquier formato, de hasta 64 KB. Un mensaje puede permanecer en la cola durante un máximo de 7 días. A partir de la versión del 2017-07-29, inclusive, el tiempo de vida máximo puede ser cualquier número positivo o -1, lo que indica que el mensaje no expira. Si se omite este parámetro, el tiempo de vida predeterminado es siete días.

En el siguiente diagrama se muestra la relación entre estos recursos.

Diagram of Queue storage architecture

Use las siguientes clases de Python para interactuar con estos recursos:

  • QueueServiceClient: La clase QueueServiceClient permite administrar todas las colas de la cuenta de almacenamiento.
  • QueueClient: La clase QueueClient permite administrar y manipular una cola individual y sus mensajes.
  • QueueMessage: La clase QueueMessage representa los objetos individuales que se devuelven al llamar a receive_messages en una cola.

Ejemplos de código

Estos fragmentos de código de ejemplo muestran cómo realizar las siguientes acciones con la biblioteca cliente de Azure Queue Storage para Python:

Autorización del acceso y creación de un objeto de cliente

Asegúrese de que está autenticado con la misma cuenta de Microsoft Entra a la que asignó la función. Puede autenticarse a través de la CLI de Azure, Visual Studio Code o Azure PowerShell.

Inicie sesión en Azure a través de la CLI de Azure mediante el siguiente comando:

az login

Una vez que se autentique, puede crear y autorizar un objeto QueueClient mediante DefaultAzureCredential para acceder a los datos de la cola en la cuenta de almacenamiento. DefaultAzureCredential detecta y usa automáticamente la cuenta con la que ha iniciado sesión en el paso anterior.

Para autorizar mediante DefaultAzureCredential, asegúrese de que ha agregado el paquete azure.identity, como se describe en Instalación de los paquetes. Además, asegúrese de agregar la siguiente instrucción import en el archivo queues-quickstart.py:

from azure.identity import DefaultAzureCredential

Decida un nombre para la cola y cree una instancia de la clase QueueClient mediante DefaultAzureCredential para la autorización. Usaremos este objeto de cliente para crear e interactuar con el recurso de cola en la cuenta de almacenamiento.

Importante

Los nombres de la cola solo puede incluir letras minúsculas, números y guiones y debe empezar por una letra o un número. Antes y después de cada guion debe ir un carácter que no sea otro guión. El nombre debe tener entre 3 y 63 caracteres. Para más información sobre la nomenclatura de las colas, consulte Asignación de nombres a colas y metadatos.

Agregue el código siguiente dentro del bloque try y asegúrese de reemplazar el valor del marcador de posición <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)

Los mensajes de la cola se almacenan como texto. Si quiere almacenar datos binarios, configure las funciones de codificación y descodificación de Base64 antes de colocar un mensaje en la cola.

Puede configurar las funciones de codificación y descodificación de Base64 durante la creación del objeto de 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()
                        )

Creación de una cola

Con el objeto QueueClient, llame al método create_queue para crear la cola en la cuenta de almacenamiento.

Agregue este código al final del bloque try:

    print("Creating queue: " + queue_name)

    # Create the queue
    queue_client.create_queue()

Adición de mensajes a una cola

El siguiente fragmento de código agrega mensajes a la cola, para lo que debe llamar al método send_message. También guarda la clase QueueMessage devuelta desde la tercera llamada a send_message. La clase saved_message se utiliza para actualizar el contenido del mensaje más adelante en el programa.

Agregue este código al final del bloque 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")

Lectura de los mensajes de una cola

Lea los mensajes de la cola, para lo que debe llamar al método peek_messages. Este método recupera uno o varios mensajes de la parte delantera de la cola, pero no modifica la visibilidad del mensaje.

Agregue este código al final del bloque 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)

Eliminación de un mensaje de una cola

Actualice el contenido de un mensaje mediante una llamada al método update_message. Este método puede cambiar tanto el contenido como el tiempo de espera de visibilidad de un mensaje. El contenido del mensaje debe ser una cadena con codificación UTF-8 de hasta 64 KB de tamaño. Junto con el nuevo contenido, pase los valores del mensaje que se guardó anteriormente en el código. Los valores saved_message identifican el mensaje que se va a actualizar.

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

la longitud de la cola

Puede obtener una estimación del número de mensajes existentes en una cola.

El método get_queue_properties devuelve propiedades de cola, incluida approximate_message_count.

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

El resultado es aproximado, ya que se pueden agregar o borrar mensajes después de que el servicio responda la solicitud.

mensajes de una cola

Puede descargar los mensajes que ha agregado anteriormente, para lo que debe llamar al método receive_messages.

Agregue este código al final del bloque try:

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

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

Al llamar al método receive_messages, puede especificar opcionalmente un valor para max_messages, que es el número de mensajes que se van a recuperar de la cola. El valor predeterminado es 1 mensaje y el máximo es 32 mensajes. También puede especificar un valor para visibility_timeout, que oculta los mensajes de otras operaciones durante el período de tiempo de espera. El valor predeterminado es 30 segundos.

Eliminación de mensajes de una cola

Elimine los mensajes de la cola una vez recibidos y procesados. En este caso, el procesamiento solo muestra el mensaje en la consola.

La aplicación se detiene para la entrada del usuario mediante una llamada a input antes de procesar y eliminar los mensajes. Compruebe en Azure Portal que los recursos se crearon correctamente, antes de que se eliminen. Los mensajes que no se eliminen explícitamente volverán a estar visibles en la cola para que se procesen.

Agregue este código al final del bloque 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)

Eliminación de una cola

El siguiente código limpia los recursos que creó la aplicación; para ello, elimina la cola mediante el método delete_queue.

Agregue este código al final del bloque try y guarde el archivo:

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

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

    print("Done")

Ejecución del código

Esta aplicación crea y agrega tres mensajes a una cola de Azure. El código muestra los mensajes en la cola y, a continuación, los recupera y los elimina antes de eliminar la cola.

En la ventana de la consola, vaya al directorio que contiene el archivo queues-quickstart.py y, a continuación, use el siguiente comando python para ejecutar la aplicación.

python queues-quickstart.py

La salida de la aplicación es similar a la del ejemplo siguiente:

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

Cuando la aplicación se detiene antes de recibir mensajes, compruebe la cuenta de almacenamiento en Azure Portal. Compruebe que los mensajes están en la cola.

Presione la tecla Enter para recibir y eliminar los mensajes. Cuando se le solicite, presione de nuevo la tecla Enter para eliminar la cola y finalizar la demostración.

Pasos siguientes

En este inicio rápido, ha aprendido a crear una cola y a agregarle mensajes mediante código de Python. Después aprendió a ver, recuperar y eliminar mensajes. Por último, ha aprendido a eliminar una cola de mensajes.

Para ver tutoriales, ejemplos, artículos de inicio rápido y otra documentación, visite:

Azure para desarrolladores de Python