Optimizing Data Access and Messaging - Queue Service Concepts

http://msdn.microsoft.com/en-us/library/dd179353.aspx

Addressing Queue Service Resources

The Queue service exposes the following resources via the REST API:

• Account. The storage account is a uniquely identified entity within the storage system. The account is the parent namespace for the Queue service. All queues are associated with an account.
  
  
• Queue. A queue stores messages that may be retrieved by a client application or service.
  
  
• Messages. Messages are XML-compliant and may be up to 8 KB in size.
  
  

Resource URI Syntax

Each resource has a corresponding base URI, which refers to the resource itself.

For the storage account, the base URI for queue operations includes the name of the account only:

          http://myaccount.queue.core.windows.net        

For a queue, the base URI includes the name of the account and the name of the queue:

          http://myaccount.queue.core.windows.net/myqueue        

For messages in a queue, the base URI includes the name of the account, the name of the queue, and the set of messages in that queue:

          http://myaccount.queue.core.windows.net/myqueue/messages        

An individual message may be deleted by referring to the message ID. Note that this syntax is available only to the Delete Message operation and requires a popreceipt parameter for verification:

          http://myaccount.queue.core.windows.net/myqueue/messages/messageid?popreceipt=string-value        

Each resource may also have components, which are expressed as part of the query string on the base URI. The syntax for the query string is ?comp=<component_name>. Currently, the following resource components are available for queue resources, as parameters on the URI.

ComponentSupported resourcesDescription

list

Account

Enumerates the entities beneath this resource. On the account, returns the list of queues.

metadata

Queue

Sets or returns queue properties, including user-defined metadata.

Note that all values for query parameters must be URL encoded before they are sent to the Windows Azure storage services.

Supported HTTP Operations

Each resource supports a set of operations based on the HTTP verbs GET, PUT, HEAD, and DELETE. The following table lists the available operations for each resource.

 

VerbResourceQuery parameterDescription

GET

Account

?comp=list

Returns the list of all queues under this storage account.

Queue

?comp=metadata

Returns queue properties, including user-defined metadata.

Messages

None

Returns one or more messages from the front of the queue. A retrieved message is expected to be deleted and is not visible to other clients unless the specified visibility timeout expires without the message being deleted.

Messages

?peekonly=true

Returns one or more messages from the front of the queue, without altering the message's visibility to other clients. Only visible messages may be retrieved with this operation.

PUT

Queue

None

Creates a new queue.

POST

Messages

None

Adds a message to the back of the queue.

HEAD

Queue

?comp=metadata

Returns queue properties, including user-defined metadata.

DELETE

Queue

None

Deletes the queue and all of its messages.

Queue

?comp=metadata

Deletes any metadata on the queue.

Messages

None

Clears all messages from the queue.

Message

?popreceipt=<string-value>

Deletes a specified message from the queue.

Naming Queues and Metadata

Updated: November 22, 2010

Queues are organized by storage account. A URI to refer to a queue includes the account name and the queue name, as follows:

http://myaccount.queue.core.windows.net/myqueue

The URI to reference a queue must be unique. Because every account name is unique,two accounts can have queues with the same name. However, within an account, every queue must have a unique name.

All queues are created beneath the storage account; it's not possible to nest queues.

Queue Names

The queue name must be a valid DNS name, conforming to the following naming rules:

1. A queue name must start with a letter or number, and may containonly letters, numbers, and the dash (-)character. 
   
   
2. The first and last letters in the queue name must bealphanumeric. The dash (-) character may not be the first or last letter.Consecutive dash characters are not permittedin the queue name; every dash character must be immediately preceded and followed by a letter or number.
   
   
3. All letters in a queue name must be lowercase.
   
   
4. A queue name must be from 3 through 63 characters long.
   
   

Metadata Names

Metadata for a queue resource is stored as a name-value pair associated with the resource. Beginning with version 2009-09-19, metadata names must adhere to the naming rules for C# identifiers.

Existing metadata names that do not adhere to these naming rules can be used with earlier versions of the Queue service, but not with version 2009-09-19 or later.

Note that metadata names preserve the case with which they were created,but are case-insensitive when set or read. If two or more metadata headers with the same name are submitted for a resource, the Queue service returns status code 400 (Bad Request).

Setting Server Timeouts for Queue Service Operations

Each operation in the Queue service API has an optional request parameter timeout, which sets the server timeout in seconds. The timeout interval begins as soon as the server receives the request. If the operation does not complete within the specified timeout interval, a timeout error is returned. If no timeout value is specified,the default timeout of 30 seconds is used.Thirty seconds is also the maximum timeout interval for all Queue service operations.

For example, the following URI representation sets the timeout interval for the list queues operation to 20 seconds.

GET http://myaccount.queue.core.windows.net?comp=list&timeout=20

If you specify a timeout interval that is greater than that specified by the service, the service's timeout is used. If you specify a timeout that is less than the service's default timeout, then your timeout interval will be used.