Using Subscriptions

Goal

Imagine you want to create a subscription that sends a notification via email to your customer when an order is created.

Following diagram simplifies the approach. Creating a subscription with the message 'Order Created' --- and the right queue information --- creates a message queue in SQS or SB. A client can then poll a message from the queue and --- according to its body --- apply an action for example sending an email notification.

Prerequisites

1. For this tutorial, you need credentials for an API client. If you don't have an API client yet, please create one with scope Manage Subscriptions as described in the documentation.

2. Additionally, as mentioned earlier, this tutorial covers two paths:

• You can either use AWS SQS. In this case, you need to have an AWS account, and to create an SQS queue. Here is an additional link that helps you get started with SQS: Getting Started with Amazon SQS.

• Or you can use Azure Service Bus (ASB). In this case, you need to have an Azure account, and to create a queue in the Service Bus. Following link helps you to start with Azure Service Bus: Create a queue using the Azure portal.

Create a Subscription

Before we create a subscription, we need to gather some data from the queue service, we are using.

The next two subsections describe how to use SQS and ASB respectively. If you are using AWS SQS proceed with the next subsection, otherwise jump to the Azure Service Bus subsection.

Access and Queue

AWS

First of all, you need an access key ID and a secret access key. Follow this tutorial to find out how to create your own security credentials.

Then, you need a queue in SQS. This tutorial leads you through the creation of a queue and getting the URL and the region of the queue.

Azure

First, you need to create a queue in the SB. When you create the queue, make sure that the checkbox "Enable sessions" is unchecked, since this option is not supported by the API.

The second step is to get the connection string needed to create an ASB subscription. This link helps you to accomplish this task.

Messages

As mentioned earlier, messages is an array of message subscriptions which require a resource type ID. Here is a list of the currently supported resourceTypeId.

Following code snippets show examples of passing order as resourceTypeId in different languages.

Code Snippets for an AWS Subscription

{
  "destination": {
    "type": "SQS",
    "queueUrl": "<url-to-my-queue>",
    "authenticationMode": "IAM",
    "region": "<my-region>"
  },
  "messages": [
    {
      "resourceTypeId": "order"
    }
  ]
}

Code Snippets for an SB Subscription

<?php
$destination = AzureServiceBusDestination::ofQueueURLAccessKeyAndSecret(
   'Endpoint=sb://<namespace>.servicebus.windows.net/;SharedAccessKeyName=<key-name>;SharedAccessKey=<key>;EntityPath=<queue-name>',
);
$messages = MessageSubscriptionCollection::of()->add(
   MessageSubscription::of()->setResourceTypeId('order'),
);
$subscriptionDraft = SubscriptionDraft::ofDestinationAndMessages(
   $destination,
   $messages,
);
$request = SubscriptionCreateRequest::ofDraft($subscriptionDraft);
$response = $client->execute($request);
$subscription = $request->mapResponse($response);

If the creation of the subscription was successful you will get a response similar to this:

An AWS subscription

{
  "changes": [],
  "createdAt": "<timestamp>",
  "destination": {
    "accessKey": "<my-access-key>",
    "accessSecret": "<my-access-secret>",
    "queueUrl": "<my-queue-url>",
    "region": "<my-region>",
    "type": "SQS",
    "authenticationMode": "Credentials"
  },
  "id": "<subscription-id>",
  "lastModifiedAt": "<timestamp>",
  "messages": [
    {
      "resourceTypeId": "order",
      "types": []
    }
  ],
  "version": 1
}

An SB subscription

{
  "changes": [],
  "createdAt": "<timestamp>",
  "destination": {
    "connectionString": "<my-connectionString>",
    "type": "AzureServiceBus"
  },
  "id": "<subscription-id>",
  "lastModifiedAt": "<timestamp>",
  "messages": [
    {
      "resourceTypeId": "order",
      "types": []
    }
  ],
  "version": 1
}

Example of Receiving a Message using PHP and SQS

Now, let's receive a message from the queue and use the content of its body to send the notification to the user. To receive a message, we have to poll it from the queue. For the purpose of this tutorial, we will only print the message we receive in the browser. In the following example code we use PHP. But you are free to use any language you prefer.

Create a PHP file with the snippet below. For the client we used the factory method, see the SQS documentation for more details.

$client = SqsClient::factory(array(
    'profile' => '<my-profile>',
    'region'  => '<my-region>'
));

$result = $client->receiveMessage(array(
    'QueueUrl' => <my-queue-url>,
));

foreach ($result->getPath('Messages/*/Body') as $messageBody) {
    // Do something with the message
    echo $messageBody;
}

When you run this code, and if you have a message in your queue, you will see its body in the browser.

Further Learning

From here, you can discover other subscription options, for example, updating and deleting subscriptions, as well as other predefined messages.