Skip to main content

Using the Amazon SQS Messaging API

InterSystems provides an API you can use to produce and consume messages using the Amazon Simple Queue Service (SQS). Your code acts as a producer or consumer by creating a client, then calling the client’s methods to perform actions like sending and receiving messages. InterSystems IRIS also provides methods to create and delete Amazon SQS queues.

The Amazon SQS API is based on the common messaging classes that are shared by other messaging platforms. This page describes platform-specific variations in the work flow which these common classes establish.

In addition to the API described here, InterSystems provides specialized classes that you can use to send messages to Amazon SQS and retrieve messages from Amazon SQS as part of an interoperability production.

Connecting to Amazon SQS

To create a connection to Amazon SQS:

  1. Create a settings object. To do this create an instance of %External.Messaging.SQSSettingsOpens in a new tab and set its properties as follows:

    • credentialsFile, a string specifying the location of your Amazon Simple Storage Service (S3) credentials file.

    • accessKey, a string containing your Amazon S3 access key. If you have specified a credentialsFile, you do not need to set this property.

    • secretKey, a string containing your Amazon S3 secret key. If you have specified a credentialsFile, you do not need to set this property.

    • sessionToken, a string containing an Amazon S3 session token. If you have specified a credentialsFile which includes a session token, you do not need to set this property.

    • region, a string specifying an Amazon S3 region.

    For example:

     Set settings = ##class(%External.Messaging.SQSSettings).%New()
     Set settings.credentialsFile = "~/.aws/credentials/cred.ini"
     Set settings.region = "us-east-1"
    
  2. Create the messaging client object. To do this, call the CreateClient() method of the generic %External.Messaging.ClientOpens in a new tab class, passing the settings object as the first argument. For example:

     Set client = ##class(%External.Messaging.Client).CreateClient(settings, .tSC)
     If $$$ISERR(tSC) {
           //handle error scenario
     }

    The method returns a status code by reference as the second argument. Your code should check the status before proceeding.

    Because the settings object is an instance of %External.Messaging.SQSSettingsOpens in a new tab, the returned object (client) is an instance of %External.Messaging.SQSClientOpens in a new tab.

Amazon SQS Producers

InterSystems IRIS can act as an Amazon SQS publisher by calling API methods to create messages and then send them. If the application needs to create the topics where messages will be sent, see Working with Queues. The following flow uses the client object to interact with Amazon SQS as a publisher:

Set Message Attributes (Optional)

To attach custom metadata to your message using Amazon SQS message attributes, you must create an InterSystems IRIS %ListOfObjects Opens in a new tabcollection of SQS message attribute objects. The Amazon SQS message object you will create in the next section will accepts this list of attributes as an optional property. For each attribute you want to define:

  1. Create a new instance of the %External.Messaging.SQSMessageAttributeOpens in a new tab object.

  2. Set the properties of the message attribute object:

    • key, the message attribute key

    • dataType, the data type of the message attribute value ("String", "Number", or "Binary")

    • stringValue or binaryValue, the message attribute value. Set the property appropriate to the data type you have specified.

  3. Add each message attribute object to your list of message attribute objects.

Refer to the Amazon SQS message metadata documentationOpens in a new tab for more information about message attributes. The following example prepares a time stamp attribute:

 Set attrList = ##class(%ListOfObjects).%New()

 Set key = "timestamp"
 Set dataType = "String"
 Set value = $zdatetime($horolog)

 Set msgAttr1 = ##class(%External.Messaging.SQSMessageAttribute).%New()
 Set msgAttr1.key = key
 Set msgAttr1.dataType = dataType
 Set msg.stringValue = value

 Set tSC = attrList.Insert(msgAttr1)
Create Message

To prepare a message to be sent, create a new instance of the %External.Messaging.SQSMessageOpens in a new tab object. Then, define properties for that message object. You must specify the name of the destination queue and the body of the message. If you have defined custom message attributes as described in the previous section, provide the list of message attribute objects as the messageAttributes property. For example:

 Set queue = "quick-start-events"
 Set body = "MyMessage"

 Set msg = ##class(%External.Messaging.SQSMessage).%New()
 Set msg.queue = queue
 Set msg.body = body
 Set msg.messageAttributes = attrList
Send Message

After creating a message, you can send it to the topic by executing the SendMessage() method for the Amazon SQS client object:

 set tSC = client.SendMessage(msg)
 if $$$ISERR(tSC) {
       //handle error scenario
 }

Amazon SQS Consumers

InterSystems IRIS can act as an Amazon SQS consumer by calling an API method to retrieve messages for a topic. The following flow uses the client object to interact with Amazon SQS as a consumer:

Configure Settings for Message Retrieval (Optional)

The Amazon SQS client can use the ReceiveMessage() method to act as an Amazon SQS consumer. This method allows you to specify settings for the message retrieval operation by providing a JSON-formatted string as an optional argument. To do so, create a new instance of the %External.Messaging.SQSReceiveSettingsOpens in a new tab class and set properties as desired. The following properties are available:

  • maxNumberOfMessages, an integer specifying the maximum number of messages to return

  • waitTimeSeconds, an integer specifying the number of seconds before polling timeout

  • visibilityTimeout, an integer specifying the number of seconds during which the messages returned by the method are effectively invisible to other consumers

For example:

 Set rset = ##class(%External.Messaging.SQSReceiveSettings).%New()
 Set rset.waitTimeSeconds = 5
 Set rset.visibilityTimeout = 30
Retrieve Messages

To retrieve messages, invoke the ReceiveMessage() method inherited by the Amazon SQS client object. This method takes the name of a queue as an argument and returns messages as a %ListOfObjectsOpens in a new tab by reference. If you have specified message retrieval settings as described in the preceding section, provide these settings as a third argument using the ToJSON() method. For example:

 #dim messages As %ListOfObjects
 Set tSC = client.ReceiveMessage(queue, .messages, rset.ToJSON())
Delete Messages from the Queue

An Amazon SQS consumer is responsible for deleting messages from a queue as the consumer receives and processes them. To delete a message, invoke the DeleteMessage() method for the client object. DeleteMessage() requires you to provide the name of the queue as the first argument and the receipt handle for the message as the second argument. The receipt handle is stored in the receiptHandle property for each message object the ReceiveMessage() method returns.

 For i=1:1:messages.Size {
        Set msg = messages.GetAt(i)
        Write "Message: ", msg.ToJSON(), !
        Set tSC = client.DeleteMessage(queue, msg.receiptHandle)
 }

Working with Queues

InterSystems IRIS provides an API that can be used to create and delete Amazon SQS queues.

Specify Queue Settings (Optional)

If you would like to specify settings for your queue, create an %External.Messaging.SQSQueueSettings object and set the properties of that object corresponding to your desired settings. For more information about the configuration options available, refer to the Amazon SQS documentationOpens in a new tab.

For example, the following code creates a queue settings object which specifies a first-in-first-out queue and delays the delivery of all messages in the queue for five seconds:

 Set queueSet = ##class(%External.Messaging.SQSQueueSettings).%New()
 Set queueSet.FifoQueue = 1
 Set queueSet.DelaySeconds = 5
Create a Queue

To create a queue, invoke the CreateQueue() method of the client object. CreateQueue() requires you to provide a queue name as an argument. If you have created a queue settings object for the queue (as described in the previous section), you may provide this object as an optional second argument.

 Set queue = "quick-start-events"
 Set tSC = client.CreateQueue(queue, queueSet)

As an alterative, you can create the queue with a method that is common to all messaging platforms. When using this alternative, you can provide the contents of your queue settings object as a JSON object using the ToJSON() method. See %External.Messaging.Client.CreateQueueOrTopic()Opens in a new tab for details.

Delete a Queue

An application can delete an Amazon SQS queue by invoking the DeleteTopic() method of the client object. This method accepts the queue name as an argument.

 Set tSC = client.DeleteQueue(queue)

As an alterative, you can delete the queue with a method that is common to all messaging platforms. See %External.Messaging.Client.DeleteQueueOrTopic()Opens in a new tab for details.

Close Client

An InterSystems IRIS application that is done communicating with Amazon SQS should close the client with the Close() method. For example:

 Do:client'="" client.Close()
FeedbackOpens in a new tab