Examinar o ver mensajes

La exploración de mensajes, o la inspección, permite a un cliente de Service Bus enumerar todos los mensajes de una cola o una suscripción con fines de diagnóstico o depuración.

La operación de inspección de una cola o una suscripción devuelve como máximo el número solicitado de mensajes. En la tabla siguiente se muestran los tipos de mensajes devueltos por la operación de inspección.

Tipo de mensajes	¿Se incluye?
Mensajes activos	Sí
Mensajes fallidos	No
Mensajes bloqueados	Sí
Mensajes diferidos	Sí
Mensajes expirados	Puede ser (antes de que se les haya enviado un mensaje fallido)
Mensajes programados	Sí, para las colas. No, para suscripciones.

Mensajes fallidos

Para ver los mensajes fallidos de una cola o suscripción, la operación de inspección debe ejecutarse en la cola de mensajes no enviados asociada a la cola o la suscripción. Para obtener más información, vea Ruta de acceso para la cola de mensajes fallidos.

Mensajes expirados

Los mensajes que han expirado se pueden incluir en los resultados devueltos por la operación de inspección. Los mensajes consumidos y expirados se limpian mediante una ejecución de "recolección de elementos no utilizados" asincrónica. Este paso no se produce necesariamente al instante después de que expiren los mensajes. Por eso, una operación de inspección puede devolver mensajes que ya han expirado. Estos mensajes se quitarán o se pondrán en la cola de mensajes fallidos cuando se invoque una operación de recepción en la cola o la suscripción la próxima vez. Tenga en cuenta este comportamiento al intentar recuperar los mensajes aplazados de la cola.

Un mensaje expirado ya no es apto para la recuperación normal mediante ningún otro medio, incluso cuando se devuelve con Peek. Estos mensajes se devuelven por diseño dado que Peek es una herramienta de diagnóstico que refleja el estado actual del registro.

Mensajes bloqueados

La operación de inspección también devuelve los mensajes que estaban bloqueados y que actualmente son procesados por otros receptores. Sin embargo, dado que Peek devuelve una instantánea desconectada, el estado de bloqueo de un mensaje no se puede observar en los mensajes inspeccionados.

Mensajes diferidos

Los mensajes aplazados permanecen en la cola principal junto con todos los demás mensajes activos (a diferencia de los mensajes fallidos que están activos en una subcola), pero ya no se reciben mediante las funciones de recepción habituales. Los mensajes aplazados se pueden detectar a través de la exploración de mensajes si una aplicación pierde su pista.

Para recuperar un mensaje aplazado, su propietario es responsable de recordar la propiedad el número de secuencia cuando se aplaza. Cualquier receptor que conozca el número de secuencia de un mensaje aplazado puede recibir el mensaje más adelante mediante métodos de recepción que toman el número de secuencia como parámetro. Para obtener más información sobre los números de secuencia, consulte Secuenciación y marcas de tiempo de los mensajes.

API de Peek

La operación de inspección es compatible con las colas y suscripciones y con las colas correspondientes de mensajes fallidos.

Cuando se llama repetidamente a la operación de inspección, se enumeran todos los mensajes del registro de la cola o la suscripción, por orden, desde el número de secuencia más bajo disponible hasta el más alto. Este es el orden en que los mensajes se ponen en cola; no es el orden en que finalmente se podrían recuperar.

También se puede pasar un valor de SequenceNumber a una operación de inspección. Este valor se usa para determinar por dónde empezar la operación de inspección. Posteriormente, puede llamar a la operación de inspección sin especificar el parámetro para que la enumeración sea más amplia.

Número máximo de mensajes

Puede especificar el número máximo de mensajes que desea que devuelva la operación de inspección. Sin embargo, no hay ninguna manera de garantizar un tamaño mínimo para el lote. El número de mensajes devueltos depende de varios factores, de los cuales el más impactante es la rapidez con la que la red puede transmitir mensajes al cliente. 

Este es un fragmento de código de ejemplo para ver todos los mensajes con el SDK de Service Bus de Python. sequence_number​ se puede usar para realizar un seguimiento del último mensaje inspeccionado y empezar a examinar a partir del siguiente mensaje.

C#

using Azure.Messaging.ServiceBus;

// Create a Service Bus client for your namespace
ServiceBusClient client = new ServiceBusClient("NAMESPACECONNECTIONSTRING");

// Create Service Bus receiver for your queue in the namespace
ServiceBusReceiver receiver = client.CreateReceiver("QUEUENAME");

// Peek operation with max count set to 5
var peekedMessages = await receiver.PeekMessagesAsync(maxMessages: 5);

// Keep receiving while there are messages in the queue
while (peekedMessages.Count > 0)
{
    int counter = 0; // To get the sequence number of the last peeked message
    int countPeekedMessages = peekedMessages.Count;

    if (countPeekedMessages > 0)
    { 
        // For each peeked message, print the message body
        foreach (ServiceBusReceivedMessage msg in peekedMessages)
        {
            Console.WriteLine(msg.Body);
            counter++;
        }
        Console.WriteLine("Peek round complete");
        Console.WriteLine("");
    }

    // Start receiving from the message after the last one
    var fromSeqNum = peekedMessages[counter-1].SequenceNumber + 1;
    peekedMessages = await receiver.PeekMessagesAsync(maxMessages: 5, fromSequenceNumber: fromSeqNum);
}

La siguiente salida de ejemplo procede de examinar una cola con 13 mensajes en ella.

Message 1
Message 2
Message 3
Message 4
Message 5
Peek round complete

Message 6
Message 7
Message 8
Message 9
Message 10
Peek round complete

Message 11
Message 12
Message 13
Peek round complete

Python

import os
from azure.servicebus import ServiceBusClient

CONNECTION_STR = os.environ['SERVICEBUS_CONNECTION_STR']
QUEUE_NAME = os.environ["SERVICEBUS_QUEUE_NAME"]

servicebus_client = ServiceBusClient.from_connection_string(conn_str=CONNECTION_STR)

with servicebus_client:
    receiver = servicebus_client.get_queue_receiver(queue_name=QUEUE_NAME, prefetch=500)
    with receiver:
        peeked_msgs = receiver.peek_messages(max_message_count=500)
        # keep receiving while there are messages in the queue
        while len(peeked_msgs) > 0:
            for msg in receiver:
                print(msg)
            # start receiving from the message after the last one
            from_seq_num = peeked_msgs[-1].sequence_number + 1
            peeked_msgs = receiver.peek_messages(max_message_count=500, sequence_number=from_seq_num)

print("Receive is done.")

Contenido relacionado

Pruebe los ejemplos en el lenguaje que prefiera para explorar las características de Azure Service Bus.

• Ejemplos de la biblioteca cliente de Azure Service Bus para .NET (versión más reciente): ejemplo de envío y recepción de mensajes.
• Ejemplos de la biblioteca cliente de Azure Service Bus para Java (versión más reciente) - ejemplo de Pico en un mensaje
• Ejemplos de la biblioteca cliente de Azure Service Bus para Python - Ejemplo de receive_peek.py
• Ejemplos de la biblioteca cliente de Azure Service Bus para JavaScript - Ejemplo de browseMessages.js
• Ejemplos de la biblioteca cliente de Azure Service Bus para TypeScript - Ejemplo de browseMessages.js

Encuentre ejemplos de las bibliotecas cliente de .NET y Java anteriores aquí:

• Ejemplos de biblioteca cliente de Azure Service Bus para .NET (heredado) - ejemplo de exploración de mensajes (ver el código sin salir)
• Ejemplos de biblioteca cliente de Azure Service Bus para Java (heredado) - ejemplo de exploración de mensajes.

El 30 de septiembre de 2026, retiraremos las bibliotecas del SDK de Azure Service Bus WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus y com.microsoft.azure.servicebus, que no se ajustan a las directrices del SDK de Azure. También retiraremos el soporte del protocolo SBMP, por lo que ya no podrás usar este protocolo después del 30 de septiembre de 2026. Migre a las bibliotecas más recientes del SDK de Azure, que ofrecen actualizaciones de seguridad críticas y funcionalidades mejoradas, antes de esa fecha.

Aunque las bibliotecas anteriores todavía se pueden usar después del 30 de septiembre de 2026, ya no recibirán soporte técnico oficial ni actualizaciones de Microsoft. Para obtener más información, consulte el anuncio de retirada de soporte técnico.