Queue Service REST API Reference

Introduction

The Azure Queue service is a collection of REST APIs for managing queues and the messages within them. It provides a simple, scalable way to decouple application components and to communicate between them asynchronously.

The Queue service supports the following operations:

• Creating and deleting queues.
• Adding, retrieving, and deleting messages from queues.
• Retrieving queue metadata.

All Queue service operations are exposed via HTTP or HTTPS and are callable from any language that can make an HTTP request.

Authentication

Requests to the Azure Queue service must be authenticated. Authentication is typically performed using Shared Key authentication or Azure Active Directory (Azure AD) authentication.

Shared Key Authentication: This method uses the storage account's access keys. You construct a signature string that includes request details and the secret key to generate an authentication header.

Azure AD Authentication: For more secure scenarios, you can use Azure AD to grant access to your storage queues. This allows for fine-grained access control and integrates with Azure RBAC.

For detailed information on constructing the authorization header, please refer to the Microsoft Azure Storage Authentication documentation.

Service Endpoints

The base URI for Queue service operations follows this format:

https://<your-storage-account-name>.queue.core.windows.net/<queue-name>

Where:

• <your-storage-account-name> is the name of your storage account.
• <queue-name> is the name of the queue you are targeting.

For operations on the service level (e.g., listing queues), the URI is:

https://<your-storage-account-name>.queue.core.windows.net/

Queue Operations

This section details the REST API operations for managing queues.

Create a Queue

The PUT Queue operation creates a new queue within the specified storage account.

Request Headers:

Header	Description
x-ms-version	Specifies the version of the Queue service API to use for the request.
Authorization	Required. The authorization credentials for the request.
x-ms-date	Required. The UTC date/time of the request.
x-ms-meta-name	Optional. User-defined metadata key-value pairs.

Response:

Status Code	Description
201 Created	Indicates that the queue was successfully created.
409 Conflict	Indicates that a queue with the same name already exists.

Delete a Queue

The DELETE Queue operation deletes a specified queue and all the messages it contains.

Request Headers:

Header	Description
x-ms-version	Specifies the version of the Queue service API to use for the request.
Authorization	Required. The authorization credentials for the request.
x-ms-date	Required. The UTC date/time of the request.

Response:

Status Code	Description
204 No Content	Indicates that the queue was successfully deleted.
404 Not Found	Indicates that the specified queue does not exist.

List Queues

The GET Queues operation lists all queues in the specified storage account.

Query Parameters:

Parameter	Type	Description
prefix	String	Filters the results to return queues whose names begin with the specified prefix.
maxresults	Integer	Specifies the maximum number of queues to return.
marker	String	Specifies a string value that identifies the position in the list of queues at which to begin the listing.

Response:

<QueueList>
  <Queues>
    <Queue>
      <Name>myqueue</Name>
      <Metadata>
        <my-key>my-value</my-key>
      </Metadata>
    </Queue>
    <Queue>
      <Name>anotherqueue</Name>
    </Queue>
  </Queues>
  <NextMarker>marker-for-next-page</NextMarker>
</QueueList>

Message Operations

These operations allow you to interact with messages within a queue.

Put Message

The POST Message operation adds a new message to the end of a specified queue.

Request Body:

<QueueMessage>
  <MessageText>Your message content here.</MessageText>
</QueueMessage>

Response:

<QueueMessagesList>
  <QueueMessage>
    <MessageId>GUID-of-the-message</MessageId>
    <InsertionTime>ISO8601-time</InsertionTime>
    <ExpirationTime>ISO8601-time</ExpirationTime>
    <PopReceipt>receipt-value</PopReceipt>
    <DequeueCount>0</DequeueCount>
    <MessageText>Your message content here.</MessageText>
  </QueueMessage>
</QueueMessagesList>

Get Messages

The GET Messages operation retrieves one or more messages from the front of a specified queue.

Query Parameters:

Parameter	Type	Description
numofmessages	Integer	Specifies the number of messages to retrieve, up to 32.
visibilitytimeout	Integer	Specifies the time interval, in seconds, to make the message invisible.

Response:

<QueueMessagesList>
  <QueueMessage>
    <MessageId>GUID-of-the-message</MessageId>
    <InsertionTime>ISO8601-time</InsertionTime>
    <ExpirationTime>ISO8601-time</ExpirationTime>
    <PopReceipt>receipt-value</PopReceipt>
    <DequeueCount>1</DequeueCount>
    <MessageText>Your message content here.</MessageText>
  </QueueMessage>
</QueueMessagesList>

Delete Message

The DELETE Message operation deletes a specific message from a queue.

Query Parameters:

Parameter	Type	Description
popreceipt	String	Required. The valid pop receipt value obtained from retrieving the message.

Response:

Status Code	Description
204 No Content	Indicates that the message was successfully deleted.
404 Not Found	Indicates that the message or queue does not exist, or the pop receipt is invalid.

Clear Queue

The DELETE Messages operation clears all messages from a specified queue.

Response:

Status Code	Description
204 No Content	Indicates that the queue was successfully cleared.

Metadata

You can associate metadata with queues and messages. Metadata is stored as name-value pairs. All metadata names are case-insensitive and must adhere to the naming conventions for HTTP headers. Metadata values are case-sensitive.

Setting Queue Metadata:

Metadata is set when creating a queue using the x-ms-meta-name header or updated using the SET Properties operation.

Getting Queue Metadata:

Queue metadata is returned as part of the GET Queue Properties operation.