AWS Simple Queue Service

This library implements Amazon Simple Queue Service (SQS) actions in agent code.

You can view the library’s source code on GitHub. Click here to see information on the available versions of this library.

To include this library in your project, add the following lines to the top of your agent code:

#require "AWSRequestV4.class.nut:1.0.2"
#require "AWSSQS.agent.lib.nut:1.0.0"

Note AWSRequestV4 must be included before the AWSSQS library.

Class Usage

Constructor: AWSSQS(region, accessKeyId, secretAccessKey)

The constructor takes the following parameters, all of which are required:

Parameter	Type	Description
region	string	AWS region (eg. `"us-west-2"`)
accessKeyId	string	IAM Access Key ID
secretAccessKey	string	IAM Secret Access Key

Example

const AWS_SQS_ACCESS_KEY_ID     = "<YOUR_ACCESS_KEY_ID>";
const AWS_SQS_SECRET_ACCESS_KEY = "<YOUR_SECRET_ACCESS_KEY>";
const AWS_SQS_URL               = "<YOUR_SQS_URL>";
const AWS_SQS_REGION            = "<YOUR_REGION>";

// Instantiate the class
sqs <- AWSSQS(AWS_SQS_REGION, AWS_SQS_ACCESS_KEY_ID, AWS_SQS_SECRET_ACCESS_KEY);

Class Methods

action(actionType, params, callback)

Performs the specified action (eg. ‘send a message’) with the required parameters.

Parameter	Type	Description
actionType	Constant	Type of Amazon SQS action that you want to perform (see Action Types, below)
params	Table	Table of action-specific parameters (see Action Parameters, below)
callback	Function	Callback function that takes one parameter: a Callback Response Table

Action Types

The currently supported actionType values are listed in the table below. Each action’s set of required and optional parameters (as passed into the params table in the action() call) are listed after the table.

Action Type	Description
AWSSQS_ACTION_SEND_MESSAGE	Delivers a message to a specified queue
AWSSQS_ACTION_SEND_MESSAGE_BATCH	Delivers up to ten messages to a specified queue
AWSSQS_ACTION_RECEIVE_MESSAGE	Retrieves one or more messages (up to ten) from a specified queue
AWSSQS_ACTION_DELETE_MESSAGE	Deletes the specified message from the specified queue
AWSSQS_ACTION_DELETE_MESSAGE_BATCH	Deletes up to ten messages from a specified queue

Action Parameters

Specific actions of the types listed above are configured by passing information into action()’s params parameter as a table with the following action type-specific keys.

AWSSQS_ACTION_SEND_MESSAGE

Delivers a message to the specified queue. Please view the AWS SQS documentation for more information.

Parameter	Type	Required?	Default	Description
QueueUrl	String	Yes	N/A	The URL of the Amazon SQS queue from which messages are sent
DelaySeconds	Integer	No	`null`	The number of seconds to delay a specific message. Valid values: 0 to 900
MessageAttribute.<N>.Name	String	No	`null`	See the AWS SQS documentation for more details. <N> Starting from 1
MessageAttribute.<N>.Value.StringValue	String, integer or blob	No	`null`	Message attributes allow you to provide structured metadata (such as timestamps, geospatial data, signatures and identifiers) about the message
MessageAttribute.<N>.Value.DataType	String	No	`null`	Type of MessageAttribute.<N>.Value.StringValue determined by MessageAttribute.<N>.Value.DataType
MessageBody	String	Yes	N/A	The message to send. The maximum string size: 256KB
MessageDeduplicationId	String	No	`null`	This parameter applies only to FIFO (first in, first out) queues. The token used for deduplication of sent messages. If a message with a particular MessageDeduplicationId is sent successfully, any messages sent with the same MessageDeduplicationId are accepted successfully but aren’t delivered during the five-minute deduplication interval
MessageGroupId	String	No	`null`	This parameter applies only to FIFO (first in, first out) queues. The tag that specifies that a message belongs to a specific message group. Messages that belong to the same message group are processed in a FIFO manner (messages in different message groups might be processed out of order)

Example

local sendParams = {
  "QueueUrl"    : "https://some.aws.sqs.url",
  "MessageBody" : "testMessage"
};

sqs.action(AWSSQS_ACTION_SEND_MESSAGE, sendParams, function(response) {
  server.log(http.jsonencode(response));
});

Example with Message Attributes

local sendParams = {
    "QueueUrl"                              : "https://some.aws.sqs.url",
    "MessageAttribute.1.Name"               : "test_attribute_name_1",
    "MessageAttribute.1.Value.StringValue"  : "test_attribute_value_1",
    "MessageAttribute.1.Value.DataType"     : "String",
    "MessageAttribute.2.Name"               : "test_attribute_name_2",
    "MessageAttribute.2.Value.StringValue"  : "test_attribute_value_2",
    "MessageAttribute.2.Value.DataType"     : "String",
    "MessageBody"                           : "testMessage"
};

sqs.action(AWSSQS_ACTION_SEND_MESSAGE, sendParams, function(response) {
    server.log(http.jsonencode(response));
});

AWSSQS_ACTION_SEND_MESSAGE_BATCH

Delivers up to ten messages to the specified queue. Please view the AWS SQS documentation for more information.

Parameter	Type	Required?	Description
QueueUrl	String	Yes	The URL of the Amazon SQS queue from which messages are sent
SendMessageBatchRequestEntry.<N>.<X>	String	Yes	A list of SendMessageBatchResultEntry items. Where <N> is the message entry number and <X> is the SendMessageBatchResultEntry parameter

SendMessageBatchRequestEntrys consist of:

Parameter	Type	Required?	Default	Description
DelaySeconds	Integer	No	`null`	The number of seconds to delay a specific message. Valid values: 0 to 900
MessageAttribute.<N>.Name	String	No	`null`	See the AWS SQS documentation for more details. <N> Starting from 1
MessageAttribute.<N>.Value.StringValue	String, integer or blob	No	`null`	Message attributes allow you to provide structured metadata (such as timestamps, geospatial data, signatures and identifiers) about the message
MessageAttribute.<N>.Value.DataType	String	No	`null`	Type of MessageAttribute.<N>.Value.StringValue determined by MessageAttribute.<N>.Value.DataType
MessageBody	String	Yes	N/A	The message to send. The maximum string size: 256KB
MessageDeduplicationId	String	No	`null`	This parameter applies only to FIFO (first in, first out) queues. The token used for deduplication of sent messages. If a message with a particular MessageDeduplicationId is sent successfully, any messages sent with the same MessageDeduplicationId are accepted successfully but aren’t delivered during the five-minute deduplication interval
MessageGroupId	String	No	`null`	This parameter applies only to FIFO (first in, first out) queues. The tag that specifies that a message belongs to a specific message group. Messages that belong to the same message group are processed in a FIFO manner (messages in different message groups might be processed out of order)

Example

local messageBatchParams = {
  "QueueUrl": "https://some.aws.sqs.url",
  "SendMessageBatchRequestEntry.1.Id": "m1",
  "SendMessageBatchRequestEntry.1.MessageBody": "testMessage1",
  "SendMessageBatchRequestEntry.2.Id": "m2",
  "SendMessageBatchRequestEntry.2.MessageBody": "testMessage2",
};

sqs.action(AWSSQS_ACTION_SEND_MESSAGE_BATCH, messageBatchParams, function(response) {
  server.log(response.statuscode);
});

Example With Message Attributes

local messageBatchParams = {
    "QueueUrl"                                                              : "https://some.aws.sqs.url",
    "SendMessageBatchRequestEntry.1.Id"                                     : "m1",
    "SendMessageBatchRequestEntry.1.MessageBody"                            : "testMessage1",
    "SendMessageBatchRequestEntry.2.Id"                                     : "m2",
    "SendMessageBatchRequestEntry.2.MessageAttribute.1.Name"                : "test_attribute_name_1",
    "SendMessageBatchRequestEntry.2.MessageAttribute.1.Value.StringValue"   : "test_attribute_value_1",
    "SendMessageBatchRequestEntry.2.MessageAttribute.1.Value.DataType"      : "String",    
    "SendMessageBatchRequestEntry.2.MessageBody"                            : "testMessage2",
};

sqs.action(AWSSQS_ACTION_SEND_MESSAGE_BATCH, messageBatchParams, function(response) {
    server.log(response.statuscode);
});

AWSSQS_ACTION_RECEIVE_MESSAGE

Retrieves one or more messages (up to ten), from the specified queue. Please view the AWS SQS documentation for more information.

Parameter	Type	Required?	Default	Description
QueueUrl	String	Yes	N/A	The URL of the Amazon SQS queue from which messages are received
AttributeName.<N>	Array of strings	No	`null`	A list of attributes that need to be returned along with each message. See the linked document above for details
MaxNumberOfMessages	Integer	No	`null`	The maximum number of messages to return. Between one and ten messages may be selected to be returned
MessageAttributeName.<N>	Array of strings	No	`null`	The name of the message attribute, where <N> is the index
ReceiveRequestAttemptId	String	No	`null`	This parameter applies only to FIFO (first in, first out) queues. The token used for deduplication of ReceiveMessage calls. If a networking issue occurs after a ReceiveMessage action, and you receive a generic error, you can retry the same action with an identical ReceiveRequestAttemptId
VisibilityTimeout	Integer	No	`null`	The duration (in seconds) that the received messages are hidden from subsequent retrieve requests after being retrieved by a ReceiveMessage request
WaitTimeSeconds	Integer	No	`null`	The duration (in seconds) for which the call waits for a message to arrive in the queue before returning. If a message is available, the call returns sooner than WaitTimeSeconds

Example

local receiptHandleFinder = function(messageBody) {
  // Extract the reciept handle from the returned XML
  local start   = messageBody.find("<ReceiptHandle>");
  local finish  = messageBody.find("/ReceiptHandle>");
  local receipt = messageBody.slice((start + 15), (finish - 1));
  return receiptHandle;
};

// Receive Message
local receiveParams = {
  "QueueUrl": "https://some.aws.sqs.url"
};

sqs.action(AWSSQS_ACTION_RECEIVE_MESSAGE, receiveParams, function(response) {
  if (response.statuscode &gt;= 200 && response.statuscode &lt; 300) {
    server.log(receiptHandleFinder(response.body));
  }
});

AWSSQS_ACTION_DELETE_MESSAGE

Deletes the specified message from the specified queue. You specify the message by using the message’s receipt handle and not the MessageId you receive when you send the message. Please view the AWS SQS documentation for more information.

Parameter	Type	Required?	Description
QueueUrl	String	Yes	The URL of the Amazon SQS queue from which messages are deleted
ReceiptHandle	String	Yes	The receipt handle associated with the message to delete

Example

Please refer to the Receive Message example, above, to see how you obtain receiptHandle.

deleteParams <- {
  "QueueUrl": "https://some.aws.sqs.url",
  "ReceiptHandle": receiptHandle
}

sqs.action(AWSSQS_ACTION_DELETE_MESSAGE, deleteParams, function(receiptHandle) {
  server.log(receiptHandle.statuscode);
});

AWSSQS_ACTION_DELETE_MESSAGE_BATCH

Deletes up to ten messages from the specified queue. This is a batch version of DeleteMessage. The result of the action on each message is reported individually in the response. Please view the AWS SQS documentation for more information.

Parameter	Type	Required?	Description
QueueUrl	String	Yes	The URL of the Amazon SQS queue from which messages are deleted
DeleteMessageBatchRequestEntry.<N>.<X>	String	Yes	A list of DeleteMessageBatchResultEntry items where <N> is the message entry number and <X> is the SendMessageBatchResultEntry parameter

DeleteMessageBatchRequestEntrys consist of:

Parameter	Type	Required?	Description
Id	String	Yes	An identifier for this particular receipt handle
ReceiptHandle	String	Yes	The receipt handle associated with the message to be deleted

Example

Please refer to the Receive Message example, above, to see how you obtain receiptHandle, and to the Send Message Batch example, above, to learn where the batch of messages were placed.

local deleteParams = {
  "QueueUrl": "https://some.aws.sqs.url",
  "DeleteMessageBatchRequestEntry.1.Id": "m1",
  "DeleteMessageBatchRequestEntry.1.ReceiptHandle": receiptHandle
}

sqs.action(AWSSQS_ACTION_DELETE_MESSAGE_BATCH, deleteParams, function(response) {
  server.log(response.statuscode);
});

Callback Response Table

The format of the response table is common to all actions:

Key	Type	Description
body	String	AWS SQS response in a function-specific structure that is JSON encoded
statuscode	Integer	HTTP status code
headers	Table	See below

The headers table consists of the following keys:

Key	Type	Description
x-amzn-requestid	String	Amazon request ID
content-type	String	Content type, eg. `"text/XML"`
date	String	The date and time at which the response was sent
content-length	String	The length of the content
x-amz-crc32	String	Checksum of the UTF-8 encoded bytes in the HTTP response

Release History

The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.

Version	Source Code	Notes
1.0.0	GitHub	Initial release

License

The AWSSQS library is licensed under the MIT License.

AWS Simple Queue Service

Version: 1.0.0

Class Usage

Constructor: AWSSQS(region, accessKeyId, secretAccessKey)

Example

Class Methods

action(actionType, params, callback)

Action Types

Action Parameters

AWSSQS_ACTION_SEND_MESSAGE

Example

Example with Message Attributes

AWSSQS_ACTION_SEND_MESSAGE_BATCH

Example

Example With Message Attributes

AWSSQS_ACTION_RECEIVE_MESSAGE

Example

AWSSQS_ACTION_DELETE_MESSAGE

Example

AWSSQS_ACTION_DELETE_MESSAGE_BATCH

Example

Callback Response Table

Release History

License