Message Buffers are small, temporary message caches that enable “Web programming model” scenarios. Such situations arise when you cannot use an Service Bus binding to create a message consumer. This scenario can arise if your consumer is written in Java, or if it is running on a non-Windows computer or on a mobile device. In this scenario, the message consumer uses Http calls to poll for messages, and the message buffer provides a place where messages sit for a short time until the polling request picks them up.
This sample demonstrates how to program the message buffer using its REST protocol. The message buffer protocol is an HTTP REST-based API that is designed to follow common REST principles. As such, you can easily leverage the protocol from any client without requiring the Windows Azure SDK. The protocol relies on the ACS HTTP authentication model to help enforce access control on the message buffer. Specifically, it uses the Simple Web Token (SWT) mechanism to retrieve a token using HTTP, then embeds it in an HTTP request as a header. This token includes claims that are used to determine whether or not an operation should be allowed.
Each message buffer has a unique URI in the Service Bus namespace. This URI is the "root" for a set of resources that represent the message buffer "instance." Each resource, in turn, has a unique URI and can be acted upon by a set of HTTP verbs. The URIs are organized in a way that helps convey the logical relationships between the different types of resources.
The verbs which act upon resources are modeled upon the standard HTTP verbs.
- PUT: Creates a new resource or updates an existing resource.
-
POST: Updates an existing resource.
- DELETE: Deletes an existing resource.
- GET: Retrieves a representation of a resource.
In Windows Azure, POST is used to send credentials to the Access Control service to retrieve a WRAP token, and to send a message to the message buffer. PUT is used to create a new message buffer or to update the policy of an existing message buffer.
The following section lists common operations that can be performed on the message buffers using the REST protocol.
Request a WRAP token from ACS
To interact with the Message Buffer, you must get a token from the appropriate Service Bus issuer.
Resource URI |
|
HTTP Verb |
POST |
Request Headers |
None |
Request Body (encrypted) |
wrap_name={issuer name}&wrap_password={issuer key}&applies_to=http://{service-namespace}.servicebus.windows.net/{message-buffer-name} |
Response Body |
wrap_access_token={token}&wrap_access_token_expires_in={token-expiry-time} |
Create a new Message Buffer or update an existing one's policy
Resource URI |
https://{service-namespace}.servicebus.windows.net/{message-buffer-name} (http is valid too) |
HTTP Verb |
PUT |
Request Headers |
Authorization: WRAP access_token="{token}" Content-Type: application/atom+xml;type=entry;charset=utf-8 |
Request Body |
{policy-xml} (Please refer the "Message Buffer policy schema" section in this document) |
Response Body |
{policy-xml} (policy properties will be assigned their default values if their values in the request are absent or invalid) |
Delete a Message Buffer
Resource URI |
https://{service-namespace}.servicebus.windows.net/{message-buffer-name} |
HTTP Verb |
DELETE |
Request Headers |
Authorization: WRAP access_token="{token}" |
Request Body |
(Empty) |
Response Body |
(Empty) |
Get a Message Buffer's policy
Resource URI |
https://{service-namespace}.servicebus.windows.net/{message-buffer-name} |
HTTP Verb |
GET |
Request Headers |
Authorization: WRAP access_token="{token}" |
Request Body |
(Empty) |
Response Body |
{policy-xml} |
Send a message to the Message Buffer
Resource URI |
https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages |
HTTP Verb |
POST |
Request Headers |
Authorization: WRAP access_token="{token}" Content-Type: application/atom+xml;type=entry;charset=utf-8 |
Request Body |
{message-payload} |
Response Body |
(Empty) |
Retrieve a message in the Message Buffer (destructive read)
Resource URI |
https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages/head?timeout={timeout-in-seconds} |
HTTP Verb |
DELETE |
Request Headers |
Authorization: WRAP access_token="{token}" |
Request Body |
(Empty) |
Response Body |
{message-payload} |
Lock a message in the Message Buffer (non-destructive read)
Resource URI |
https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages/head?timeout={timeout-in-seconds}&lockduration={lockduration-in-secs} |
HTTP Verb |
POST |
Request Headers |
Authorization: WRAP access_token="{token}" |
Request Body |
(Empty) |
Response Headers |
X-MS-MESSAGE-LOCATION: https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages/{message-id} X-MS-LOCK-ID: {lock-id} X-MS-LOCK-LOCATION: https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages/{message-id}/{lock-id} |
Response Body |
{message-payload} |
Unlock a locked message in the Message Buffer
Resource URI |
https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages/{message-id}/{lock-id} |
HTTP Verb |
DELETE |
Request Headers |
Authorization: WRAP access_token="{token}" |
Request Body |
(Empty) |
Response Body |
(Empty) |
Delete a locked message from the Message Buffer
Resource URI |
https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages/{message-id}?lockid={lock-id} |
HTTP Verb |
DELETE |
Request Headers |
Authorization: WRAP access_token="{token}" |
Request Body |
(Empty) |
Response Body |
(Empty) |
Message Buffer policy XML schema
Xml | |
---|---|
<entry xmlns="http://www.w3.org/2005/Atom"><content type="text/xml"> <MessageBufferPolicy xmlns="http://schemas.microsoft.com/netservices/2009/05/servicebus/connect"> <Authorization>{AuthorizationPolicy}</Authorization> <Discoverability>{DiscoverabilityPolicy}</Discoverability> <TransportProtection>{TransportProtectionPolicy}</TransportProtection> <ExpiresAfter>hh:mm:ss</ExpiresAfter> <MaxMessageCount>nnn</MaxMessageCount> <OverflowPolicy>{OverflowPolicy}</OverflowPolicy> </MessageBufferPolicy> </content> </entry> |
The various property values are as follows:
Authorization Policy |
NotRequired, Required, RequiredToReceive, OR RequiredToSend |
Discoverability Policy |
Managers, ManagersListeners, ManagersListenersSenders, OR Public |
Transport Protection Policy |
None OR AllPaths |
Expires After |
hh:mm:ss |
Max Message Count |
nnn |
Overflow Policy | RejectIncomingMessage |
Building and Running the Sample
After building the solution, do the following to run the application:
- From a command prompt, run the service application from bin\Debug\PlainHttp.exe.
- When prompted, enter the service namespace, issuer name and the issuer key.
- The sample will create a message buffer, retrieve a message from it and delete
the message buffer.
Did you find this information useful? Please send your suggestions and comments about the documentation.