Queue Storage REST API Reference

This document provides a reference for the Azure Queue Storage REST API. Queue storage is a service that allows you to store large numbers of messages that can be accessed from anywhere in the world via HTTP or HTTPS.

Overview

Azure Queue Storage is a collection of REST APIs for managing queues and messages. It's designed for scenarios where you need to decouple components of an application and ensure reliable message delivery.

Authentication

All requests to the Queue Storage API must be authenticated. The most common methods are:

Resource URIs

The base URI for Queue Storage operations is:

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

Common Operations

Queues

Create Queue

Creates a new queue within the specified storage account.

PUT /

Headers:

Name Required Type Description
x-ms-version Yes String Specifies the version of the Queue Storage API. e.g., 2020-08-04.
Authorization Yes String Authentication credentials.
x-ms-date Yes String The date and time in RFC 1123 format.

Response:

Success (201 Created)

HTTP/1.1 201 Created
Content-Length: 0
Date: Tue, 29 Oct 2023 18:02:11 GMT
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 71f7d9f9-2001-4a57-9f25-110a11f214e1
x-ms-version: 2020-08-04
x-ms-service-request-id: 71f7d9f9-2001-4a57-9f25-110a11f214e1
x-ms-client-request-id: 8d7628c6-9c44-4a69-9b4f-1b5384622786
x-ms-resource-type: queue
x-ms-location: eastus
x-ms-sku-name: Standard_LRS
x-ms-content-crc: 0
x-ms-content-md5:
x-ms-lease-id:
x-ms-approximate-messages: 0
x-ms-meta-

List Queues

Lists all queues associated with the storage account.

GET /

Query Parameters:

Name Required Type Description
prefix No String Filters the results to return only queues whose names begin with the specified prefix.
maxresults No Integer Specifies the maximum number of queues to return.
include No String Specifies whether to include a list of metadata for each queue. Possible value: metadata.

Response:

Success (200 OK)

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 437
Date: Tue, 29 Oct 2023 18:05:00 GMT
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: a1b2c3d4-e5f6-7890-1234-567890abcdef
x-ms-version: 2020-08-04
x-ms-service-request-id: a1b2c3d4-e5f6-7890-1234-567890abcdef
x-ms-client-request-id: 9f876543-210e-4d5c-b6a5-43210fedcba9

<?xml version="1.0" encoding="utf-8"?><Queues>
  <Queue>
    <Name>myqueue1</Name>
    <ApproximateMessagesCount>15</ApproximateMessagesCount>
    <Metadata>
      <LastAccess>2023-10-29T18:00:00Z</LastAccess>
    </Metadata>
  </Queue>
  <Queue>
    <Name>anotherqueue</Name>
    <ApproximateMessagesCount>3</ApproximateMessagesCount>
  </Queue>
</Queues>

Delete Queue

Deletes a specified queue and all the messages it contains.

DELETE /

Response:

Success (204 No Content)

HTTP/1.1 204 No Content
Content-Length: 0
Date: Tue, 29 Oct 2023 18:07:30 GMT
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: c3d4e5f6-7890-1234-5678-90abcdef1234
x-ms-version: 2020-08-04
x-ms-service-request-id: c3d4e5f6-7890-1234-5678-90abcdef1234
x-ms-client-request-id: 12345678-90ab-cdef-1234-567890abcdef

Messages

Put Message

Adds a new message to the back of a specified queue.

POST //messages

Query Parameters:

Name Required Type Description
messagettl No Integer Specifies the time-to-live in seconds for the message. The maximum time-to-live is 7 days. If this parameter is omitted, the default value is 7 days.
visibilitytimeout No Integer Specifies the visibility timeout in seconds after the message is dequeued. The message is invisible to other consumers during this timeout.

Request Body:

<QueueMessage>
  <MessageText>My first message.</MessageText>
</QueueMessage>

Response:

Success (201 Created)

HTTP/1.1 201 Created
Content-Type: application/xml
Content-Length: 295
Date: Tue, 29 Oct 2023 18:10:00 GMT
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: d4e5f678-90ab-cdef-1234-567890abcdef12
x-ms-version: 2020-08-04
x-ms-service-request-id: d4e5f678-90ab-cdef-1234-567890abcdef12
x-ms-client-request-id: 210e4d5c-b6a5-4321-0fed-cba987654321

<?xml version="1.0" encoding="utf-8"?><QueueMessagesList>
  <QueueMessage>
    <MessageId>01234567-89ab-cdef-0123-456789abcdef</MessageId>
    <InsertionTime>2023-10-29T18:10:00Z</InsertionTime>
    <ExpirationTime>2023-11-05T18:10:00Z</ExpirationTime>
    <PopReceipt>BQIAAAAAAAAAICZkMzc5ZjYwOS1iNTY3LTQ5OWUtYTFmZi00NTBkOGJmYjY3YTU=</PopReceipt>
    <DequeueCount>0</DequeueCount>
  </QueueMessage>
</QueueMessagesList>

Get Messages

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

GET //messages

Query Parameters:

Name Required Type Description
numresults No Integer Specifies the number of messages to retrieve. Maximum is 32.
visibilitytimeout No Integer Specifies the visibility timeout in seconds. The message will be invisible to other consumers during this period.
peekonly No Boolean If true, messages are peeked at, not dequeued.

Response:

Success (200 OK)

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 589
Date: Tue, 29 Oct 2023 18:12:00 GMT
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: e5f67890-1234-5678-90ab-cdef12345678
x-ms-version: 2020-08-04
x-ms-service-request-id: e5f67890-1234-5678-90ab-cdef12345678
x-ms-client-request-id: 3210fedc-ba98-7654-3210-fedcba987654

<?xml version="1.0" encoding="utf-8"?><QueueMessagesList>
  <QueueMessage>
    <MessageId>01234567-89ab-cdef-0123-456789abcdef</MessageId>
    <InsertionTime>2023-10-29T18:10:00Z</InsertionTime>
    <ExpirationTime>2023-11-05T18:10:00Z</ExpirationTime>
    <PopReceipt>BQIAAAAAAAAAICZkMzc5ZjYwOS1iNTY3LTQ5OWUtYTFmZi00NTBkOGJmYjY3YTU=</PopReceipt>
    <DequeueCount>1</DequeueCount>
    <MessageText>My first message.</MessageText>
  </QueueMessage>
  <QueueMessage>
    <MessageId>fedcba98-7654-3210-fedc-ba9876543210</MessageId>
    <InsertionTime>2023-10-29T18:11:30Z</InsertionTime>
    <ExpirationTime>2023-11-05T18:11:30Z</ExpirationTime>
    <PopReceipt>BQIAAAAAAAAAIJmN5Zjk2MDktYTU2Ny00OTlmLWExZmYtNDUwZDhiZmI2N2E1</PopReceipt>
    <DequeueCount>0</DequeueCount>
    <MessageText>Another message.</MessageText>
  </QueueMessage>
</QueueMessagesList>

Delete Message

Deletes a specific message from a queue. This operation is used after a message has been retrieved and processed successfully.

DELETE //messages/?popreceipt=

Query Parameters:

Name Required Type Description
popreceipt Yes String A valid pop receipt value returned from a previous call to Get Messages.

Response:

Success (204 No Content)

HTTP/1.1 204 No Content
Content-Length: 0
Date: Tue, 29 Oct 2023 18:15:00 GMT
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: f6789012-3456-7890-abcd-ef1234567890
x-ms-version: 2020-08-04
x-ms-service-request-id: f6789012-3456-7890-abcd-ef1234567890
x-ms-client-request-id: 43210fed-cba9-8765-4321-0fedcba98765
« Previous: File Storage API Next: Table Storage API »