Microsoft Azure Documentation

Azure Storage Queues REST API

Introduction

The Azure Storage Queues REST API provides a programmatic interface for interacting with Azure Storage queues. Queues are a way to store large numbers of messages that can be accessed by multiple processes.

This API allows you to perform operations such as creating, listing, and deleting queues, as well as enqueuing, dequeuing, and peeking at messages within a queue. You can manage queue metadata, set time-to-live for messages, and control message visibility.

Authentication

Requests to the Azure Storage Queues REST API must be authenticated. The primary methods of authentication are:

  • Shared Key Authentication: Uses account keys to sign requests.
  • Shared Access Signatures (SAS): Provides delegated access to resources for a limited time.
  • Azure Active Directory (Azure AD): For more robust security and integration with identity management.

For detailed information on authentication methods, refer to the Azure Storage authentication documentation.

Core Operations

Queue Operations

These operations manage the queues themselves:

  • Create Queue: Creates a new queue.
    • URI: PUT /{accountName}/queues/{queueName}
    • Description: Creates a new queue with the specified name.
  • List Queues: Lists all queues within the storage account.
    • URI: GET /{accountName}/queues
    • Description: Retrieves a list of queues, optionally filtered and with metadata.
  • Get Queue Metadata: Retrieves metadata for a specific queue.
    • URI: GET /{accountName}/queues/{queueName}
    • Description: Returns the queue's properties, such as approximate message count.
  • Delete Queue: Deletes a queue and all of its messages.
    • URI: DELETE /{accountName}/queues/{queueName}
    • Description: Permanently removes the specified queue.
  • Set Queue Metadata: Sets metadata on a queue.
    • URI: PUT /{accountName}/queues/{queueName}
    • Description: Updates the metadata for an existing queue.

Message Operations

These operations manage messages within a queue:

  • Enqueue Message: Adds a message to the queue.
    • URI: POST /{accountName}/queues/{queueName}/messages
    • Description: Inserts a new message into the queue.
  • Dequeue Message: Retrieves and deletes the next message in the queue.
    • URI: GET /{accountName}/queues/{queueName}/messages
    • Description: Retrieves the first message and makes it invisible for a specified timeout.
  • Peek Message: Retrieves the next message without deleting it.
    • URI: GET /{accountName}/queues/{queueName}/messages?peekonly=true
    • Description: Returns the next message without changing its visibility or removing it from the queue.
  • Get Messages: Retrieves multiple messages from the queue.
    • URI: GET /{accountName}/queues/{queueName}/messages?numofmessages={count}
    • Description: Retrieves up to a specified number of messages.
  • Delete Message: Deletes a specific message from the queue.
    • URI: DELETE /{accountName}/queues/{queueName}/messages/{messageId}?popreceipt={popReceipt}
    • Description: Deletes a message using its ID and pop receipt.
  • Clear Queue: Deletes all messages from a queue.
    • URI: DELETE /{accountName}/queues/{queueName}/messages
    • Description: Removes all messages from the queue.
  • Update Message: Updates the visibility of a message or its contents.
    • URI: PUT /{accountName}/queues/{queueName}/messages/{messageId}?popreceipt={popReceipt}
    • Description: Updates a message's visibility timeout or dequeues it again with new content.

Code Examples

Here are some basic examples using cURL to demonstrate common operations:

Example 1: Enqueue a message


curl -X POST \
  "https://myaccount.queue.core.windows.net/myqueue/messages?&timeout=90&api-version=2020-08-04" \
  -H "Content-Type: application/xml" \
  -H "Date: Tue, 25 Oct 2022 21:59:49 GMT" \
  -H "Authorization: SharedKey myaccount:abcd..." \
  -d '<QueueMessage><MessageText>Hello, World!</MessageText></QueueMessage>'

Example 2: Dequeue a message


curl -X GET \
  "https://myaccount.queue.core.windows.net/myqueue/messages?numofmessages=1&visibilitytimeout=30&api-version=2020-08-04" \
  -H "Date: Tue, 25 Oct 2022 21:59:49 GMT" \
  -H "Authorization: SharedKey myaccount:abcd..."

Example 3: Delete a message


curl -X DELETE \
  "https://myaccount.queue.core.windows.net/myqueue/messages/message-id-12345?popreceipt=abcde...&api-version=2020-08-04" \
  -H "Date: Tue, 25 Oct 2022 21:59:49 GMT" \
  -H "Authorization: SharedKey myaccount:abcd..."

Further Reading and References