메시지 찾아보기 또는 피킹

  • 아티클

메시지 검색 또는 피킹을 사용하여 Service Bus 클라이언트는 큐 또는 구독의 모든 메시지를 진단 및 디버깅 용도로 열거할 수 있습니다.

큐 또는 구독에 대한 피킹 작업은 요청된 메시지 수를 반환합니다. 다음 표에서는 피킹 작업에서 반환되는 메시지 유형을 보여 줍니다.

메시지 유형 포함 여부
활성 메시지 예
배달 못한 메시지 아니요
잠긴 메시지 예
지연된 메시지 예
만료된 메시지 포함될 수 있음(배달 못한 편지로 처리되기 전)
예약된 메시지 큐의 경우 예입니다. 구독의 경우 아니요

배달 못한 메시지

큐 또는 구독의 배달 못한 편지로 처리됨 메시지로 피킹하려면 큐 또는 구독과 연결된 배달 못한 큐에서 피킹 작업을 실행해야 합니다. 자세한 내용은 배달 못한 편지 큐 액세스를 참조하세요.

만료된 메시지

만료된 메시지는 피킹 작업에서 반환된 결과에 포함될 수 있습니다. 사용된 메시지 및 만료된 메시지는 비동기 "가비지 수집"을 실행하여 정리됩니다. 이 단계는 메시지가 만료된 직후에 반드시 발생하지 않을 수도 있습니다. 그렇기 때문에 미리 보기 작업을 수행하면 이미 만료된 메시지가 반환될 수 있습니다. 이런 메시지는 다음에 큐 또는 구독에서 수신 작업이 호출될 때 제거되거나 배달되지 못한 편지로 처리됩니다. 지연된 메시지를 큐에서 복구하려고 시도할 때 이런 동작에 유의해야 합니다.

만료된 메시지는 어떠한 방법으로도(Peek에 의해 반환되는 경우에도) 일반 검색을 수행할 수 없습니다. Peek은 로그의 현재 상태를 반영하는 진단 도구이기 때문에 해당 메시지를 반환하는 것은 의도적입니다.

잠긴 메시지

또한, 피킹은 잠겨서 현재 다른 수신기가 처리하는 메시지를 반환합니다. 그러나 Peek은 연결이 끊긴 스냅샷을 반환하기 때문에 피킹 메시지에서 메시지의 잠금 상태를 관찰할 수 없습니다.

지연된 메시지

연기된 메시지는 다른 모든 활성 메시지와 함께 기본 큐에 남아 있지만(하위 큐에 유지되는 배달 못 한 메시지와 다름), 더 이상 일반 수신 작업을 사용하여 수신될 수 없습니다. 연기된 메시지는 애플리케이션이 추적하지 못할 경우 메시지 찾아보기를 통해 검색할 수 있습니다.

지연된 메시지를 검색하기 위해 해당 소유자는 시퀀스 번호를 지연할 때 기억해야 합니다. 지연된 메시지의 시퀀스 번호를 알고 있는 모든 수신자는 시퀀스 번호를 매개 변수로 사용하는 수신 방법을 사용하여 나중에 메시지를 수신할 수 있습니다. 시퀀스 번호에 대한 자세한 내용은 메시지 순서 지정 및 타임 스탬프를 참조하세요.

Peek API

피킹은 큐, 구독 및 배달 못한 메시지 큐에서 작동합니다.

반복적으로 호출되면 피킹 작업은 큐 또는 구독에 있는 모든 메시지를 순서대로(가장 낮은 시퀀스 번호에서 가장 높은 시퀀스 번호로) 열거합니다. 다음은 메시지를 큐에 넣는 순서이며 최종적으로 메시지가 검색되는 순서는 아닙니다.

또한 피킹 작업에 SequenceNumber를 전달할 수 있습니다. 피킹을 시작할 위치를 결정하는 데 사용됩니다. 추가로 열거할 매개 변수를 지정하지 않고도 피킹 작업에 대한 후속 호출을 수행할 수 있습니다.

최대 메시지 수

미리 보기 작업에서 반환할 최대 메시지 수를 지정할 수 있습니다. 그러나 일괄 처리의 최소 크기를 보장할 수 있는 방법은 없습니다. 반환된 메시지 수는 여러 요소에 따라 달라지며, 그중 가장 영향을 미치는 요소는 네트워크가 클라이언트에 메시지를 얼마나 빨리 스트리밍할 수 있는지입니다. 

다음은 Python Service Bus SDK를 사용하여 모든 메시지를 피킹하기 위한 예제 코드 조각입니다. sequence_number​를 사용하면 마지막으로 본 메시지를 추적하고 다음 메시지에서 찾아보기를 시작할 수 있습니다.

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

다음 샘플 출력은 13개 메시지가 포함된 큐를 피킹하는 것입니다.

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

관련 콘텐츠

선택한 언어로 샘플을 사용하여 Azure Service Bus 기능을 살펴봅니다.

이전 .NET 및 Java 클라이언트 라이브러리에 대한 샘플은 다음을 참조하세요.

2026년 9월 30일에 Azure SDK 지침을 따르지 않는 Azure Service Bus SDK 라이브러리 WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus 및 com.microsoft.azure.servicebus를 사용 중지합니다. 또한 SBMP 프로토콜에 대한 지원이 종료되므로 2026년 9월 30일 이후에는 더 이상 이 프로토콜을 사용할 수 없습니다. 해당 날짜 마이그레이션에 중요한 보안 업데이트와 개선된 기능을 제공하는 최신 Azure SDK 라이브러리로 마이그레이션합니다.

이전 라이브러리는 2026년 9월 30일 이후에도 계속 사용할 수 있지만 더 이상 Microsoft로부터 공식 지원 및 업데이트를 받을 수 없습니다. 자세한 내용은 사용 중지 공지 지원을 참조하세요.