Azure Documentation

Working with Queue Messages

This document provides detailed information on how to work with messages in Azure Storage queues. Azure Queues is a service that allows you to store a large number of messages that can be accessed from anywhere in the world via HTTP or HTTPS.

Message Structure

Each message in an Azure Storage queue is represented as a string. While you can store any string content, it's common practice to encode binary data (like a JSON payload) using Base64 encoding to ensure it's safely transmitted as a string.

Core Operations

1. Enqueueing a Message (Put Message)

Adding a message to the queue is done using the Put Message operation. The message content is sent in the request body.

from azure.storage.queue import QueueClient

queue_name = "my-queue"
connection_string = "YOUR_CONNECTION_STRING"

queue_client = QueueClient.from_connection_string(connection_string, queue_name)

message_text = "This is a sample message."
queue_client.send_message(message_text)
print(f"Message '{message_text}' sent to queue '{queue_name}'.")

2. Dequeueing Messages (Get Messages)

You can retrieve one or more messages from the queue using the Get Messages operation. When you retrieve messages, they become invisible to other clients for a specified visibility timeout. This prevents other clients from processing the same message simultaneously.

The Get Messages operation returns a list of messages. Each message object includes:

• messageid: A unique identifier for the message.
• popreceipt: A receipt that must be used for subsequent operations like deleting or updating the message.
• content: The actual message payload.
• insertiontime: The time the message was inserted.
• expirationtime: The time the message will expire.
• nextvisibletime: The time when the message will become visible again if not deleted.

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

String queueUrl = "YOUR_QUEUE_URL";
String credential = "YOUR_CREDENTIAL"; // e.g., SAS token or connection string

QueueClient queueClient = new QueueClientBuilder()
    .url(queueUrl)
    .credential(credential)
    .buildClient();

// Get up to 5 messages with a 30-second visibility timeout
List<QueueMessage> messages = queueClient.receiveMessages(5, java.time.Duration.ofSeconds(30)).getValue();

for (QueueMessage message : messages) {
    System.out.println("Message ID: " + message.getMessageId());
    System.out.println("Pop Receipt: " + message.getPopReceipt());
    System.out.println("Content: " + message.getBody().toString());
    // Process the message here...
}

3. Updating a Message (Update Message)

You can extend the visibility timeout of a message or update its content using the Update Message operation. This is useful if your processing of a message takes longer than initially anticipated.

using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;
using System;

string connectionString = "YOUR_CONNECTION_STRING";
string queueName = "my-queue";
string messageId = "MESSAGE_ID_TO_UPDATE";
string popReceipt = "POP_RECEIPT_OF_MESSAGE";
string newMessageContent = "Updated content for the message.";
TimeSpan visibilityTimeout = TimeSpan.FromMinutes(5);

QueueClient queueClient = new QueueClient(connectionString, queueName);

UpdateMessageResult updateResult = queueClient.UpdateMessage(messageId, popReceipt, newMessageContent, visibilityTimeout);

Console.WriteLine($"Message {messageId} updated. New pop receipt: {updateResult.PopReceipt}");

4. Completing a Message (Delete Message)

Once a message has been successfully processed, you must explicitly delete it from the queue using the Delete Message operation. This requires the message ID and its current pop receipt. If a message's visibility timeout expires before it's deleted, it becomes visible again in the queue and can be dequeued by another client.

const { QueueServiceClient } = require("@azure/storage-queue");

async function deleteMessage() {
    const connectionString = "YOUR_CONNECTION_STRING";
    const queueName = "my-queue";
    const messageId = "MESSAGE_ID_TO_DELETE";
    const popReceipt = "POP_RECEIPT_OF_MESSAGE";

    const queueServiceClient = QueueServiceClient.fromConnectionString(connectionString);
    const queueClient = queueServiceClient.getQueueClient(queueName);

    await queueClient.deleteMessage(messageId, popReceipt);
    console.log(`Message ${messageId} deleted successfully.`);
}

deleteMessage().catch((error) => {
    console.error("Error deleting message:", error);
});

Message Deferral (Peek-Lock)

The behavior of retrieving messages in Azure Queues is often referred to as "peek-lock". When a message is retrieved, it's not immediately removed. Instead, it's made invisible for a set duration (the visibility timeout). If the message is processed successfully within this timeout, it's deleted. If the timeout expires, the message reappears in the queue, ready to be processed again. This ensures that even if a client fails during processing, the message is not lost.

Queue Message Limits

• Message Size: 64 KB
• Number of Messages: Unlimited (subject to storage account limits)
• Visibility Timeout: Default is 30 seconds, can be up to 2 minutes.