Procurar ou espiar mensagens

Artigo
03/28/2024

A procura de mensagens, ou espiada, permite que um cliente do Barramento de Serviço enumere todas as mensagens em uma fila ou assinatura, para fins de diagnóstico e depuração.

A operação Peek em uma fila ou em uma assinatura retorna, no máximo, o número solicitado de mensagens. A tabela a seguir mostra os tipos de mensagens que são retornadas pela operação Peek.

Tipo de mensagens	Incluso?
Mensagens ativas	Sim
Mensagens mortas	No
Mensagens bloqueadas	Yes
Mensagens adiadas	Yes
Mensagens expiradas	Pode ser (antes de serem mortas)
Mensagens agendadas	Sim para filas. Não para assinaturas

Mensagens mortas

Para inspecionar mensagens Mortas de uma fila ou assinatura, a operação de inspecionar deve ser executada na fila de mensagens mortas associada à fila ou assinatura. Para obter mais informações, consulte acessando filas de letras mortas.

Mensagens expiradas

Mensagens expiradas podem ser incluídas nos resultados retornados da operação Peek. As mensagens consumidas e expiradas são limpas por uma execução assíncrona de "coleta de lixo". Essa etapa pode não ocorrer necessariamente logo após as mensagens expirarem. É por isso que uma operação de inspeção pode retornar mensagens que já expiraram. Essas mensagens serão removidas ou mortas quando uma operação de recebimento for invocada na fila ou assinatura na próxima vez. Mantenha esse comportamento em mente ao tentar recuperar mensagens desviadas da fila.

Uma mensagem expirada não é elegível para recuperação regular por outros meios, mesmo quando está sendo retornada por Peek. O retorno dessas mensagens é intencional, uma vez que Peek é uma ferramenta de diagnóstico refletindo o estado atual do log.

Mensagens bloqueadas

O Peek também retorna mensagens que foram bloqueadas e estão sendo processadas por outros receptores no momento. No entanto, como Peek retorna um instantâneo desconectado, o estado de bloqueio de uma mensagem não pode ser observado em mensagens inspecionadas.

Mensagens adiadas

As mensagens adiadas permanecem na fila principal junto a todas as outras mensagens ativas (ao contrário de mensagens mortas que residem em uma subfila), mas elas não podem mais ser recebidas usando as operações de recebimento regulares. Mensagens adiadas podem ser descobertas por meio da procura de mensagens se um aplicativo perder o controle delas.

Para recuperar uma mensagem adiada, seu proprietário é responsável por memorizar o número de sequência conforme ele a adia. Todo destinatário que conhecer o número de sequência de uma mensagem adiada pode receber a mensagem mais tarde usando métodos recebimento que usam o número de sequência como um parâmetro. Para obter mais informações sobre números de sequência, consulte Sequenciamento de mensagem e carimbos de data/hora.

APIs de Peek

Peek funciona em filas, assinaturas e suas filas de mensagens mortas.

Quando chamado várias vezes, a operação de inspeção enumera todas as mensagens na fila ou assinatura, em ordem, do menor número da sequência disponível até o maior. Esta é a ordem na qual as mensagens foram enfileiradas, não é a ordem na qual as mensagens podem ser recuperadas eventualmente.

Você também pode passar um SequenceNumber para uma operação de inspeção. Ele é usado para determinar de onde começar a espiar. Você pode fazer chamadas subsequentes para a operação de inspeção sem especificar o parâmetro para enumerar ainda mais.

Número máximo de mensagens

Você pode especificar o número máximo de mensagens que deseja que a operação de espiar retorne. Porém, não é possível garantir um tamanho mínimo para o lote. O número de mensagens retornadas depende de vários fatores dos quais o mais impactante é a rapidez com que a rede pode transmitir mensagens para o cliente.

Este é um exemplo de snippet para espiar todas as mensagens com o SDK do Barramento de Serviço Python. O sequence_number pode ser usado para acompanhar a última mensagem espiada e começar a navegar na próxima mensagem.

C#
Python

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);
}

A amostra de saída a seguir é obtida ao espiar uma fila com 13 mensagens.

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

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

Experimente os exemplos no idioma de sua escolha para explorar os recursos do Barramento de Serviço do Azure.

Amostras da biblioteca de clientes do Barramento de Serviço do Azure para .NET (mais recente) - - Amostra de envio e recebimento de mensagens.
Amostras da biblioteca de clientes do Barramento de Serviço do Azure para Java (mais recente) - Amostra de Peek em uma mensagem
Amostra da biblioteca de clientes do Barramento de Serviço do Azure para Python - receive_peek.py
Amostras da biblioteca de clientes do Barramento de Serviço do Azure para JavaScript - Amostra browseMessages.js
Amostras da biblioteca de clientes do Barramento de Serviço do Azure para TypeScript - Amostra browseMessages.ts

Encontre exemplos de bibliotecas de clientes .NET e Java mais antigas aqui:

Amostras da biblioteca de clientes do Barramento de Serviço do Azure para .NET (Herdado) - Amostra de Procura de Mensagens (Peek)
Amostras da biblioteca de clientes do Barramento de Serviço do Azure para Java (Herdado) - Amostra de Procura de Mensagens.

Em 30 de setembro de 2026, desativaremos as bibliotecas do SDK do Barramento de Serviço do Azure WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus e com.microsoft.azure.servicebus, que não estão em conformidade com as diretrizes do SDK do Azure. Também encerraremos o suporte ao protocolo SBMP, portanto, ele não poderá mais ser usado após 30 de setembro de 2026. Antes dessa data, migre para as bibliotecas mais recentes do SDK do Azure, que oferecem atualizações de segurança críticas e funcionalidades aprimoradas.

Embora as bibliotecas mais antigas ainda poderão ser usadas após 30 de setembro de 2026, elas não receberão mais suporte e atualizações oficiais da Microsoft. Para obter mais informações, confira o anúncio de desativação do suporte.