Peek Messages from an Azure Storage Queue

Introduction

Azure Storage Queues provide a highly scalable messaging solution for decoupling application components. Sometimes, you need to examine the contents of messages in a queue without immediately dequeueing them. This is where the "peek" operation comes in handy. Peeking allows you to view the next message in the queue, along with its visibility timeout, without deleting it.

This article demonstrates how to peek messages from an Azure Storage Queue using the Azure SDK for various programming languages.

Prerequisites

• An Azure account with an active subscription. Create one for free.
• A Storage account. Create a storage account.
• A queue within your storage account.
• Azure SDKs installed for your preferred language (e.g., .NET, Python, Java, Node.js).

Understanding the Peek Operation

When you call the PeekMessages operation on a queue, Azure Storage returns the message that would be dequeued next. Crucially, the message remains in the queue and is not deleted. The operation also returns the message's visibility timeout, which is the duration for which the message will be invisible to subsequent dequeue or peek operations. After this timeout expires, the message becomes visible again and can be dequeued.

Code Examples

Azure SDK for .NET

First, ensure you have the necessary NuGet package installed:

dotnet add package Azure.Storage.Queues

Here's an example of how to peek messages:

C#
using Azure.Storage.Queues;
using System;
using System.Threading.Tasks;

public class QueuePeekExample
{
    public static async Task Main(string[] args)
    {
        string connectionString = "";
        string queueName = "my-message-queue";

        QueueClient queueClient = new QueueClient(connectionString, queueName);

        // Ensure the queue exists (optional, depending on your workflow)
        await queueClient.CreateIfNotExistsAsync();

        // Peek up to 5 messages
        int maxMessagesToPeek = 5;
        try
        {
            Console.WriteLine($"Peeking up to {maxMessagesToPeek} messages from queue '{queueName}'...");
            Response<PeekedMessage[]> response = await queueClient.PeekMessagesAsync(maxMessagesToPeek);

            if (response.Value.Length == 0)
            {
                Console.WriteLine("No messages found in the queue.");
            }
            else
            {
                Console.WriteLine("Messages peeked:");
                foreach (PeekedMessage message in response.Value)
                {
                    Console.WriteLine($"- Message ID: {message.MessageId}");
                    Console.WriteLine($"  Content: {message.MessageText}");
                    Console.WriteLine($"  Insertion Time: {message.InsertedOn}");
                    Console.WriteLine($"  Expires On: {message.ExpiresOn}");
                    Console.WriteLine($"  Pop Receipt: {message.PopReceipt}");
                    Console.WriteLine($"  Visibility Timeout: {message.ApproximateVisibilityTimeout}");
                }
            }
        }
        catch (RequestFailedException ex)
        {
            Console.WriteLine($"Error peeking messages: {ex.Message}");
        }
    }
}
                        

Azure SDK for Python

Install the SDK:

pip install azure-storage-queue

Example:

Python
from azure.storage.queue import QueueServiceClient, PeekedMessage
import os

connection_string = os.environ.get("AZURE_STORAGE_CONNECTION_STRING", "")
queue_name = "my-message-queue"

try:
    queue_service_client = QueueServiceClient.from_connection_string(connection_string)
    queue_client = queue_service_client.get_queue_client(queue_name)

    # Create queue if it doesn't exist (optional)
    queue_client.create_queue()

    print(f"Peeking up to 5 messages from queue '{queue_name}'...")
    # Peek up to 5 messages
    peeked_messages = queue_client.peek_messages(max_messages=5)

    if not peeked_messages:
        print("No messages found in the queue.")
    else:
        print("Messages peeked:")
        for message in peeked_messages:
            print(f"- Message ID: {message.message_id}")
            print(f"  Content: {message.content}")
            print(f"  Insertion Time: {message.insertion_time}")
            print(f"  Expires On: {message.expiration_time}")
            print(f"  Pop Receipt: {message.pop_receipt}")
            print(f"  Visibility Timeout: {message.visibility_timeout}")

except Exception as e:
    print(f"Error peeking messages: {e}")
                        

Azure SDK for Java

Add the dependency to your Maven pom.xml:

XML
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-queue</artifactId>
    <version>12.17.0</version> <!-- Check for the latest version -->
</dependency>
                        

Example:

Java
import com.azure.storage.queue.QueueClient;
import com.azure.storage.queue.QueueClientBuilder;
import com.azure.storage.queue.models.PeekedMessage;
import java.util.List;

public class QueuePeekExample {

    public static void main(String[] args) {
        String connectionString = "";
        String queueName = "my-message-queue";

        try {
            QueueClient queueClient = new QueueClientBuilder()
                .connectionString(connectionString)
                .queueName(queueName)
                .buildClient();

            // Create queue if it doesn't exist (optional)
            queueClient.create();

            System.out.println("Peeking up to 5 messages from queue '" + queueName + "'...");
            // Peek up to 5 messages
            List<PeekedMessage> peekedMessages = queueClient.peekMessages(5).getValue();

            if (peekedMessages.isEmpty()) {
                System.out.println("No messages found in the queue.");
            } else {
                System.out.println("Messages peeked:");
                for (PeekedMessage message : peekedMessages) {
                    System.out.println("- Message ID: " + message.getMessageId());
                    System.out.println("  Content: " + message.getMessageText());
                    System.out.println("  Insertion Time: " + message.getInsertedOn());
                    System.out.println("  Expires On: " + message.getExpiresOn());
                    System.out.println("  Pop Receipt: " + message.getPopReceipt());
                    System.out.println("  Visibility Timeout: " + message.getApproximateVisibilityTimeout());
                }
            }
        } catch (Exception e) {
            System.err.println("Error peeking messages: " + e.getMessage());
            e.printStackTrace();
        }
    }
}
                        

Azure SDK for Node.js

Install the package:

npm install @azure/storage-queue

Example:

JavaScript
const { QueueClient } = require("@azure/storage-queue");
const connectionString = "";
const queueName = "my-message-queue";

async function peekQueueMessages() {
    const queueClient = new QueueClient(connectionString, queueName);

    try {
        // Create queue if it doesn't exist (optional)
        await queueClient.createQueue();

        console.log(`Peeking up to 5 messages from queue '${queueName}'...`);
        // Peek up to 5 messages
        const result = await queueClient.peekMessages({ numberOfMessages: 5 });

        if (!result.messages || result.messages.length === 0) {
            console.log("No messages found in the queue.");
        } else {
            console.log("Messages peeked:");
            for (const message of result.messages) {
                console.log(`- Message ID: ${message.messageId}`);
                console.log(`  Content: ${message.messageText}`);
                console.log(`  Insertion Time: ${message.insertedOn}`);
                console.log(`  Expires On: ${message.expiresOn}`);
                console.log(`  Pop Receipt: ${message.popReceipt}`);
                console.log(`  Visibility Timeout: ${message.approximateVisibilityTimeout}`);
            }
        }
    } catch (error) {
        console.error("Error peeking messages:", error.message);
    }
}

peekQueueMessages();
                        

Handling Peeked Messages

Messages peeked are not yet dequeued. If you decide a peeked message needs to be processed, you will typically follow these steps:

1. Peek the message to inspect its content.
2. If the message needs processing, dequeue it using ReceiveMessages (or GetMessages in some SDKs). This will return the message with a visibility timeout.
3. Process the message content.
4. If processing is successful, delete the message from the queue using its popReceipt.
5. If processing fails, you can either wait for the visibility timeout to expire, making the message available for redelivery, or explicitly clear the visibility timeout (though this is less common).

API Reference

For detailed information on the parameters and return values of the peek message operations, please refer to the official Azure Storage Queue API documentation:

Next Steps

Continue exploring Azure Storage Queues:

• Dequeueing and Deleting Messages
• Handling Large Messages
• Implementing Dead-Letter Queues