Skip to main content

AWS Simple Queue Service

Version: 1.0.0

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.