Accessing Windows Azure Queues from PHP

  • Article

June 7, 2012 update: The Microsoft Windows Azure team has released a new Windows Azure SDK for PHP. This release is part of an effort to keep PHP client libraries up to date with new Windows Azure features and to make PHP a first-class citizen in Windows Azure. The latest client libraries are on GitHub: https://github.com/WindowsAzure/azure-sdk-for-php. While the SDK hosted on CodePlex will continue to work for the foreseeable future, it is strongly recommended that new PHP/Windows Azure application use the SDK hosted on GitHub.

The work done by Maarten Balliauw and other contributors in building the SDK hosted on CodePlex was critical in unifying the PHP developer experience for Windows Azure. The Windows Azure team is grateful to these contributors for their pioneering work and looks forward to their continued support (and yours!) in adding to the new SDK on GitHub.

Thanks,

      
The Windows Azure Team

I recently wrote posts on how to access Windows Azure table storage from PHP and how to access Windows Azure Blob storage from PHP. To round out my look at the storage options that are available in Windows Azure, I’ll look at accessing Windows Azure queues from PHP in this post. As in the first  two posts, I’ll rely on the Windows Azure SDK for PHP to do the heavy lifting. In fact, I found the Microsoft_WindowsAzure_Storage_Queue class to be so intuitive and easy to use that I don’t think it’s worth walking you through my PHP code in this post. Instead, I’ve attached a single file that can serve as a PHP-based utility for interacting with Windows Azure queues. The PHP code in the utility should be enough to give you an understanding of how to use the Microsoft_WindowsAzure_Storage_Queue class. 

Disclaimer: The attached code isn’t necessarily pretty and is meant only to give you an idea of how Windows Azure queues work and how to use the Microsoft_WindowsAzure_Storage_Queue class. It is certainly not meant to be used as a utility for managing queues that are being used in production applications.

What I found interesting when building the utility (and what I will focus on in this post) was understanding how Windows Azure queues (and queues in general) work.

What is Windows Azure Queue?

Very simply, Windows Azure Queue is an asynchronous message (up to 8KB in size) delivery mechanism which can be used to connect different components of a cloud application. If you are familiar with a queue data structure, then you already understand the basics of Windows Azure Queue. A classic example of queue usage is in order processing. Consider a web application that accepts orders for widgets. To make order processing efficient and scalable, orders can be placed on a queue to be processed by workers that are running in the background.

image

However, as with any distributed messaging system in the cloud, Azure Queue differs from the familiar queue data structure in some important ways. Windows Azure Queue…

  • Guarantees at-least-once message delivery, which is performed in two-steps consumption: 
  1.  
    1. A worker dequeues a message and marks it as invisible
    2. A worker deletes the message when finished processing it

If worker crashes before fully processing a message, then the message becomes visible for another worker to process.

  • Doesn’t guarantee “only once” delivery. You have to build an application with the idea that a message could be delivered multiple times.
  • Doesn’t guarantee ordering of messages. Azure Queue will make a best effort at FIFO (first in, first out) message delivery, but doesn’t guarantee it. You have to build an application with this in mind.

Note that for the “order processing” example that I mentioned, all of these issues can easily be addressed (which may not be the case for other types of applications).

For a more detailed look at Azure queues, see the Windows Azure Queue: Programming Queue Storage whitepaper available here: https://www.microsoft.com/windowsazure/whitepapers/.

How do I get access to a Windows Azure Queue?

To get access to a Windows Azure Queue, you just need a Windows Azure storage account. Instructions for creating a storage account are in this earlier post (in the  How to I create a storage account? section).

How do I access a Windows Azure Queue from PHP?

In the attached script, I used the Windows Azure SDK for PHP to create and manage Windows Azure queues. I found the API to be intuitive and easy to use. Here’s a list of the methods available on the Microsoft_WindowsAzure_Storage_Queue class (note that API examples are available here, and complete documentation is available as part of the SDK download):

  • __construct([string $host = Microsoft_WindowsAzure_Storage::URL_DEV_QUEUE], [string $accountName = Microsoft_WindowsAzure_SharedKeyCredentials::DEVSTORE_ACCOUNT], [string $accountKey = Microsoft_WindowsAzure_SharedKeyCredentials::DEVSTORE_KEY], [boolean $usePathStyleUri = false], [Microsoft_WindowsAzure_RetryPolicy $retryPolicy = null])
  • clearMessages([string $queueName = ''])
  • createQueue([string $queueName = ''], [array $metadata = array()])
  • deleteMessage([string $queueName = ''], Microsoft_WindowsAzure_Storage_QueueMessage $message)
  • deleteQueue([string $queueName = ''])
  • getErrorMessage($response, [string $alternativeError = 'Unknown error.'])
  • getMessages([string $queueName = ''], [string $numOfMessages = 1], [int $visibilityTimeout = null], [string $peek = false])
  • getQueue([string $queueName = ''])
  • getQueueMetadata([string $queueName = ''])
  • isValidQueueName([string $queueName = ''])
  • listQueues([string $prefix = null], [int $maxResults = null], [string $marker = null], [int $currentResultCount = 0])
  • peekMessages([string $queueName = ''], [string $numOfMessages = 1])
  • putMessage([string $queueName = ''], [string $message = ''], [int $ttl = null])
  • queueExists([string $queueName = ''])
  • setQueueMetadata([string $queueName = ''], [array $metadata = array()])

See the attached script for examples of using almost all of these methods.

If you have used a cloud-based queue before, I don’t think you will find any “gotchas” in using this API, but here’s the things that stood out for me:

  • Queue names must be valid DNS names: https://msdn.microsoft.com/en-us/library/dd179349.aspx
  • The default time-to-live (TTL) for a message is 7 days.
  • The default visibility timeout for a message is 30 seconds. The maximum is 2 hours.
  • In order to delete a message, you must GET it first by calling getMessages() (and it must be deleted within its visibility timeout). If you retrieve a message with peekMessages(), the message will not be available for deletion.
  • The getQueue() method returns both queue metadata AND the approximate message count for the queue. (The getQueueMetadata() method only returns the queue metadata.)
  • There is no way to update queue metadata. The setQueueMetadata() method overwrites the existing queue metadata.

That’s it. If you create a storage account, download the attached script, and modify it by adding your storage account name and primary access key, you can get a better feel for how Windows Azure Queues work by actually interacting with it.

Let me know what I missed and/or what else you’d like to know.

Thanks.

-Brian

Share this on Twitter

queuestorage.zip