Procurar ou espreitar mensagens

  • Artigo

A navegação por mensagens, ou espreitar, permite que um cliente do Service Bus 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 uma assinatura retorna no máximo o número solicitado de mensagens. A tabela a seguir mostra os tipos de mensagens retornadas pela operação Peek.

Tipo de mensagens Incluído?
Mensagens ativas Sim
Mensagens com letras mortas Não
Mensagens bloqueadas Sim
Mensagens adiadas Sim
Mensagens expiradas Pode ser (antes de serem letras mortas)
Mensagens agendadas Sim para filas. Não para subscrições

Mensagens com letras mortas

Para espiar mensagens com letras mortas de uma fila ou assinatura, a operação de visualização deve ser executada na fila de letras mortas associada à fila ou assinatura. Para obter mais informações, consulte Acessando filas de letra morta.

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". Esta etapa pode não ocorrer necessariamente imediatamente após as mensagens expirarem. É por isso que uma operação de visualização pode retornar mensagens que já expiraram. Essas mensagens serão removidas ou colocadas em letras mortas quando uma operação de recebimento for invocada na fila ou na assinatura da próxima vez. Tenha esse comportamento em mente ao tentar recuperar mensagens adiadas da fila.

Uma mensagem expirada não é mais elegível para recuperação regular por qualquer outro meio, mesmo quando está sendo retornada pelo Peek. O retorno dessas mensagens é por design, pois o Peek é uma ferramenta de diagnóstico que reflete o estado atual do log.

Mensagens bloqueadas

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

Mensagens adiadas

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

Para recuperar uma mensagem adiada, seu proprietário é responsável por lembrar o número de sequência à medida que o adia. Qualquer recetor que conheça o número de sequência de uma mensagem adiada pode posteriormente receber a mensagem usando métodos de recebimento que tomam o número de sequência como parâmetro. Para obter mais informações sobre números de sequência, consulte Sequenciamento de mensagens e carimbos de data/hora.

APIs de pré-visualização

O Peek funciona em filas, assinaturas e suas filas de cartas mortas.

Quando chamada repetidamente, a operação de visualização enumera todas as mensagens na fila ou assinatura, em ordem, desde o menor número de sequência disponível até o mais alto. É a ordem em que as mensagens foram enfileiradas, não a ordem na qual as mensagens podem eventualmente ser recuperadas.

Você também pode passar um SequenceNumber para uma operação de visualização. É usado para determinar por onde começar a espreitar. Você pode fazer chamadas subsequentes para a operação peek sem especificar o parâmetro a ser enumerado 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 visualização retorne. Mas, não há como 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. 

Aqui está um trecho de exemplo para espiar todas as mensagens com o Python Service Bus SDK. O sequence_number​ pode ser usado para rastrear a última mensagem espiada e começar a navegar na próxima mensagem.

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 saída de exemplo a seguir é de espreitar 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

Conteúdos relacionados

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

Encontre exemplos para as bibliotecas de cliente .NET e Java mais antigas aqui:

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, para que você não possa mais usar esse protocolo após 30 de setembro de 2026. Migre para as bibliotecas mais recentes do SDK do Azure, que oferecem atualizações de segurança críticas e recursos aprimorados, antes dessa data.

Embora as bibliotecas mais antigas ainda possam 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, consulte o anúncio de aposentadoria de suporte.