Microsoft Azure Queue API
Go Up to Azure and Cloud Computing with DataSnap
Warning: DSAzure API is deprecated and has been replaced by Data.Cloud.AzureAPI. You are encouraged to use the new API when developing cloud computing applications. See Cloud Computing with DataSnap for more information.
The Microsoft Azure Queue API is located in the DSAzure unit, in the TAzureQueueService class. For an example of the API being used, you can look at the implementation section of the DSAzureQueue unit, which is the visual component that uses the API.
Contents
The available functions include: listing available queues, creating a queue, deleting a queue, getting the metadata for a queue, setting the metadata for a queue, adding a message to a queue, removing a message from a queue, and clearing all of the queue messages.
The following instructions will assume you already have an instance created of TAzureQueueService. In any code snippets, this instance will be referred to as FQueueService. It is also assumed that you have an XML parser at hand and that it is already configured appropriately for use. The API in some cases returns an XML, which you will need to know how to parse.
Listing Available Queues
To list the available queues, do the following:
xml := FQueueService.ListQueues([],[]);
You will now have an XML response looking something like this:
<EnumerationResults AccountName="...">
...
<Queues>
<Queue>
<Name>queue-name</Name>
<Url>queue-address</Url>
</Queue>
...
Creating a Queue
To create a new Queue, call:
FQueueService.CreateQueue('queue-name');
The queue-name must adhere to a few naming conventions:
- The name must be at least three characters in length.
- The name may only include letters, numbers, and hyphens.
- The name may not begin with a hyphen.
- The name must be all lowercase.
Deleting a Queue
To delete a queue, you simply call the following:
FQueueService.DeleteQueue('queue-name');
This will return True if the deletion was successful. The deletion on the server may take some time, so if you try to create a new queue with the same name as the queue you just deleted, this action may fail.
Reading Queue Metadata
To read a metadata value from a queue, you can do the following:
if FQueueService.GetQueueMetadata('queue-name') then
begin
Result := FQueueService.ResponseHeader['metadata-key-name'];
end;
The initial call to GetQueueMetadata returns True or False, depending on whether the metadata retrieval was successful. To read the actual metadata, you access the ResponseHeader property of the service instance.
Writing Queue Metadata
To modify the Queue metadata, you can call FQueueService.PutQueueMetadata('queue-name', MetaData), where the MetaData is a TStringList of key/value pair.
Getting the Messages of a Queue
To get the messages of a queue with name queue-name without removing the messages from the queue, do the following:
xml := FQueueService.PeekMessages('queue-name', MsgRetrieveNum);
where MsgRetrieveNum is an integer from 1 through 32. If a value less than 1 is passed, the server will return a single message. If a value greater than 32 is given, this could produce unreliable results but should in general return the maximum number of messages, which is 32.
The returned XML will look like this:
<QueueMessagesList>
<QueueMessage>
<MessageId>message-id</MessageId>
<InsertionTime>insertion-time</InsertionTime>
<ExpirationTime>expiration-time</ExpirationTime>
<DequeueCount>integer</DequeueCount>
<MessageText>queue-message-string</MessageText>
</QueueMessage>
</QueueMessagesList>
It is important to keep reference to the MessageId for later use, as it will be used to identify the specific message. For example, this is required to delete the single queue message.
If you want to see if the queue contains more than the number of messages that it returned, you can query for the total number of messages in the queue, like this:
if FQueueService.GetQueueMetadata('queue-name') then
begin
ValS := FQueueService.ResponseHeader['x-ms-approximate-messages-count'];
Result := StrToInt(ValS);
end;
Deleting Messages from a Queue
To delete messages you can either choose to delete a single message or to delete all of the messages. To delete a single message you first need to Get it, which will give you a PopReceipt, and then you can use that to delete the specific message. The code for that would look like this:
xml := FQueueService.GetMessages('queue-name', 1);
popReceipt := FQueueService.GetPopReceipt(xml);
if popReceipt <> EmptyStr then
Success := FQueueService.DeleteMessage('queue-name', MessageId, popReceipt);
The MessageId is the same MessageId returned to in the XML when you got the list of queue messages. You can see that, when calling GetMessages, you pass in a value of 1, which says to pop only the top message.
You can also delete all messages in a queue without deleting the queue itself. To do this, use the following code:
Success := FQueueService.ClearMessages('queue-name');
True is returned if the action was successful, false otherwise.
Adding a Message to a Queue
To add a new message to a queue, simply call:
Success := FQueueService.PutMessage('queue-name', MessageString);
where MessageString is the string you want to store in the message.