Installing Ruby

gem install rest-client

Create an AppFabric Service Bus

The following steps will guide you through the process of creating an AppFabric Service Bus on the AppFabric Labs.

1. Navigate to https://portal.appfabriclabs.com/, and then sign in.
2. Select ‘AppFabric Services’ from the bottom left of the page.
3. Select ‘New Namespace’ from the ribbon at the top of the page.
4. In Available Services, ensure that only Service Bus is selected.
5. Enter a namespace, for example RubyQueue.
6. Select a region, for example United States (South/Central).
7. All other settings can remain as default.
8. Click ‘Create Namespace’.

Once the namespace status changes to Active (green), you can begin working with queues within this namespace.

AppFabric Ruby Sample

The stand-alone sample can be downloaded from the AppFabric CAT team blog at http://appfabriccat.com/2011/07/using-azure-appfabric-service-bus-from-ruby-apps/.

Authentication

When accessing an AppFabric queue, you must present a Simple Web Token that authorizes you when using any of the REST APIs.  An access token can be obtained by sending a request containing the Issuer and Key values, the scope (your service bus namespace,) to the AppFabric ACS WRAP endpoint. The endpoint will return a token that can be used when calling the service bus REST APIs. An example request to the WRAP endpoint would appear as follows:

POST https://rubytest-sb.accesscontrol.appfabriclabs.com/WRAPv0.9/ HTTP/1.1
Accept: */*; q=0.5, application/xml
Content-Type: application/x-www-form-urlencoded
Accept-Encoding: gzip, deflate
Content-Length: 140
Host: rubytest-sb.accesscontrol.appfabriclabs.com
 
wrap_name=owner&wrap_password=xwCOTgOHT%2Fw8daI9mhCA8Vm0SlKYPKZojYfYCafsRaU%3D&wrap_scope=http%3A%2F%2Frubytest.servicebus.appfabriclabs.com

The value returned from the WRAP endpoint must be parsed and decoded (URL-encoding) before it can be used. The AccessControl.rb file included in the WAZ-AppFabric sample provides the get_access_token method, which invokes the WRAP endpoint and returns a decoded access token. This file also provides the get_scope helper method, which creates the scope URL needed when requesting an access token.

The following is an example of using the get_scope and get_access_token methods:

scopeUri = WAZ::AppFabric::AccessControl.get_scope(serviceNamespace)
accessToken =  WAZ::AppFabric::AccessControl.get_access_token(serviceNamespace, scopeUri, serviceIdentityName, serviceIdentityPassword)

Queue Management

The queue management REST APIs provide functionality to create, inspect, list, and delete queues within a service bus namespace. The WAZ-AppFabric sample encapsulates the calls to the REST APIs in the QueueManagement.rb file, which exposes queue management functionality through the methods in the WAZ::AppFabric::QueueMagagement class.  The operations and matching methods are described in the following table.

The following example creates, and then deletes a queue named ‘testqueue’:

createQueueResponse = WAZ::AppFabric::QueueManagement.create_queue(serviceNamespace, “testqueue”, accessToken)
deleteQueueResponse = WAZ::AppFabric::QueueManagement.delete_queue(serviceNamespace, “testqueue”, accessToken)

Queue Operations

Once created, you can use REST to send, receive, and delete messages from a queue.  The WAZ-Appfabric sample encapsulates the REST APIs to accomplish these tasks in the QueueClient.rb file, which exposes these operations through the methods in the WAZ::AppFabric::QueueClient class. The operations and matching methods are described in the following table.

The receive operation is straightforward, and is generally used when the receiving application receives and processes the application as one atomic unit of work. If there is a risk that the receiving application may fail and lose the message, such as an application that passes the message to a separate process for validation, peek-lock is more desirable, as it will place the message back into the queue if the receiving application does not explicitly delete the message within the timeout period. This behavior allows you to continuously retry processing of the message until you explicitly confirm processing by deleting the message; peek-lock and delete locked message can be used to provides a pseudo-transactional receive process.

The following is an example of sending, peek-locking, and then deleting a message to a queue named ‘testqueue’:

sendMessageResponse = WAZ::AppFabric::QueueClient.send(serviceNamespace, “testqueue”, accessToken, 'Hello, from Ruby!')
peeklockMessageResponse = WAZ::AppFabric::QueueClient.peeklock(serviceNamespace, “testqueue”, accessToken)
messageId = peeklockMessageResponse.headers[:x_ms_message_id]
lockId = peeklockMessageResponse.headers[:x_ms_lock_id]
deletelockedMessageResponse = WAZ::AppFabric::QueueClient.deletePeekedMessage(serviceNamespace, “testqueue”, accessToken, messageId, lockId)

As can be seen in this example, deleting a locked message requires information obtained from the request to peek-lock the message; specifically the message ID and lock ID.