Azure Storage Queues API Reference

This document outlines the REST API operations for Azure Storage Queues. Azure Queues is a service that enables you to store large numbers of messages that can be accessed from anywhere in the world. Use Queue storage to queue up messages that will be processed asynchronously.

Queue Operations

Create Queue

Creates a new queue within the specified storage account.

PUT /{accountName}/queues/{queueName}

Request Headers

  • x-ms-version: Specifies the version of the Queue service to use for the request.
  • Authorization: Specifies the authentication credentials.
  • Content-Length: Length of the request content.

Query Parameters

Name Type Description
timeout Integer Specifies the timeout, in seconds, relative to the time at which the request was received by the service. If not specified, the default value is 30 seconds.

Request Body

The request body is empty.

Success Response (201 Created)

Indicates that the queue was successfully created.

Get Queue Metadata

Retrieves the metadata, including the approximate message count, for the specified queue.

GET /{accountName}/queues/{queueName}

Request Headers

  • x-ms-version: Specifies the version of the Queue service to use for the request.
  • Authorization: Specifies the authentication credentials.

Query Parameters

Name Type Description
timeout Integer Specifies the timeout, in seconds, relative to the time at which the request was received by the service.

Success Response (200 OK)

<Queue>
    <ApproximateMessageCount>3</ApproximateMessageCount>
    <Metadata>
        <key1>value1</key1>
        <key2>value2</key2>
    </Metadata>
</Queue>

Delete Queue

Deletes the specified queue and all messages it contains.

DELETE /{accountName}/queues/{queueName}

Request Headers

  • x-ms-version: Specifies the version of the Queue service to use for the request.
  • Authorization: Specifies the authentication credentials.

Query Parameters

Name Type Description
timeout Integer Specifies the timeout, in seconds, relative to the time at which the request was received by the service.

Success Response (204 No Content)

Indicates that the queue was successfully deleted.

List Queues

Lists all queues in the specified storage account.

GET /{accountName}/queues

Request Headers

  • x-ms-version: Specifies the version of the Queue service to use for the request.
  • Authorization: Specifies the authentication credentials.

Query Parameters

Name Type Description
prefix String Filters queues by name, returning only those that begin with the specified prefix.
include String Specifies whether to include queue metadata in the response. Possible values: metadata.
maxresults Integer Specifies the maximum number of queues to return.
marker String A string value that identifies the position in the list of all queues. Use the value from NextMarker to continue listing results.
timeout Integer Specifies the timeout, in seconds, relative to the time at which the request was received by the service.

Success Response (200 OK)

<Queues>
    <Queue>
        <Name>myqueue</Name>
        <Metadata>
            <key1>value1</key1>
        </Metadata>
    </Queue>
    <Queue>
        <Name>anotherqueue</Name>
    </Queue>
    <NextMarker>some_marker_value</NextMarker>
</Queues>

Message Operations

Put Message

Adds a new message to the back of a queue.

POST /{accountName}/queues/{queueName}/messages

Request Headers

  • x-ms-version: Specifies the version of the Queue service to use for the request.
  • Authorization: Specifies the authentication credentials.
  • Content-Type: application/xml or application/json

Query Parameters

Name Type Description
visibilitytimeout Integer Specifies the new visibility timeout interval, in seconds, from the time of insertion. The message will be invisible until this timeout expires. The value must be between 0 and 2 minutes (120 seconds).
messagettl Integer Specifies the time-to-live interval for the message, in seconds. The value must be between 1 second and 7 days. If omitted, the default TTL is 7 days.
timeout Integer Specifies the timeout, in seconds, relative to the time at which the request was received by the service.

Request Body

<QueueMessage>
    <MessageText>This is a message</MessageText>
</QueueMessage>

Success Response (204 No Content)

Indicates that the message was successfully added.

Get Messages

Retrieves one or more messages from the front of a queue.

GET /{accountName}/queues/{queueName}/messages

Request Headers

  • x-ms-version: Specifies the version of the Queue service to use for the request.
  • Authorization: Specifies the authentication credentials.

Query Parameters

Name Type Description
numofmessages Integer Specifies the number of messages to retrieve, up to a maximum of 32. Default is 1.
visibilitytimeout Integer Specifies the new visibility timeout interval, in seconds, from the time of retrieval. The message will be invisible until this timeout expires. The value must be between 1 second and 2 minutes (120 seconds).
timeout Integer Specifies the timeout, in seconds, relative to the time at which the request was received by the service.

Success Response (200 OK)

<QueueMessages>
    <QueueMessage>
        <MessageId>a3820423-7682-478c-a824-f91b178f3c99</MessageId>
        <InsertionTime>2024-01-01T12:00:00Z</InsertionTime>
        <ExpirationTime>2024-01-08T12:00:00Z</ExpirationTime>
        <PopReceipt>ZAIzOTQzNzQtQTBCNC00RTNDLTk4MTMtNTFGNzI4MkQwNTMx</PopReceipt>
        <DequeueCount>1</DequeueCount>
        <MessageText>Hello from the queue!</MessageText>
    </QueueMessage>
    <QueueMessage>
        <MessageId>b4731534-8793-48d0-9334-092a289f4d12</MessageId>
        <InsertionTime>2024-01-01T12:01:00Z</InsertionTime>
        <ExpirationTime>2024-01-08T12:01:00Z</ExpirationTime>
        <PopReceipt>Yzk5NDM3NC1BMBC00RTNDLTk4MTMtNTFGNzI4MkQwNTMx</PopReceipt>
        <DequeueCount>1</DequeueCount>
        <MessageText>Another message.</MessageText>
    </QueueMessage>
</QueueMessages>

Delete Message

Deletes a specific message from a queue.

DELETE /{accountName}/queues/{queueName}/messages/{messageId}?popreceipt={popReceipt}

Request Headers

  • x-ms-version: Specifies the version of the Queue service to use for the request.
  • Authorization: Specifies the authentication credentials.

Query Parameters

Name Type Description
messageId GUID The ID of the message to delete.
popreceipt String The pop receipt value returned by a previous Get Messages operation.
timeout Integer Specifies the timeout, in seconds, relative to the time at which the request was received by the service.

Success Response (204 No Content)

Indicates that the message was successfully deleted.

Clear Queue

Deletes all messages from a specified queue.

DELETE /{accountName}/queues/{queueName}/messages

Request Headers

  • x-ms-version: Specifies the version of the Queue service to use for the request.
  • Authorization: Specifies the authentication credentials.

Query Parameters

Name Type Description
timeout Integer Specifies the timeout, in seconds, relative to the time at which the request was received by the service.

Success Response (204 No Content)

Indicates that the queue was successfully cleared.