AWS Simple Notification Service

Latest Version: 2.0.0

This library implements Amazon Simple Notification Service (SNS) 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 at the top of your agent code:

#require "AWSRequestV4.class.nut:1.0.2"
#require "AWSSNS.agent.lib.nut:2.0.0"

Important The AWSRequestV4 library must be included before the AWSSNS library.

Class Usage

constructor(region, accessKeyID, secretAccessKey)

Parameters

Parameter Type Required? Description
region String Yes An AWS region (eg. us-west-2)
accessKeyId String Yes Your IAM Access Key ID
secretAccessKey String Yes Your IAM Secret Access Key

Example

#require "AWSRequestV4.class.nut:1.0.2"
#require "AWSSNS.agent.lib.nut:2.0.0"

const AWS_SNS_REGION            = "<YOUR_REGION>";
const AWS_SNS_ACCESS_KEY_ID     = "<YOUR_ACCESS_KEY_ID>";
const AWS_SNS_SECRET_ACCESS_KEY = "<YOUR_SECRET_ACCESS_KEY_ID>";
const AWS_SNS_TOPIC_ARN         = "< YOUR_TOPIC_ARN_HERE>";

// Instantiate the class
sns <- AWSSNS(AWS_SNS_REGION,
              AWS_SNS_ACCESS_KEY_ID,
              AWS_SNS_SECRET_ACCESS_KEY);

Class Methods

action(actionType, params, callback)

This method performs a specified action (eg. publish) with the required parameters for the specified action’s type.

Parameters

Parameter Type Required? Description
actionType String Yes The type of the Amazon SNS action that you want to perform. See Action Types, below
params Table Yes Action-specific parameters. These are listed for each action under Action Types, below. Pass an empty table, {}, if you have no parameters to update
callback Function Yes A callback function that receives one argument, a Callback Response Table

Action Types

The following action types are provided by the library through its own constants.

Action Type Constant Description
AWSSNS_ACTIONS.CONFIRM_SUBSCRIPTION Verifies an endpoint owner’s intent to receive messages
AWSSNS_ACTIONS.LIST_SUBSCRIPTIONS Returns an XML list of the requester’s subscriptions
AWSSNS_ACTIONS.LIST_SUBSCRIPTIONS_BY_TOPIC Returns an XML list of the subscriptions to a specific topic
AWSSNS_ACTIONS.LIST_TOPICS Returns an XML list of the requester’s topics
AWSSNS_ACTIONS.PUBLISH Sends a message to an Amazon SNS topic
AWSSNS_ACTIONS.SUBSCRIBE Prepares to subscribe to an endpoint
AWSSNS_ACTIONS.UNSUBSCRIBE Deletes a subscription

AWSSNS_ACTIONS.CONFIRM_SUBSCRIPTION

Verifies an endpoint owner’s intent to receive messages by validating the token sent to the endpoint by an earlier Subscribe action. Please view the AWS SNS documentation for more information.

Action Parameters

Parameter Type Required? Description
AuthenticateOnUnsubscribe String No Disallows unauthenticated unsubscribes of the subscription. If the value of this parameter is true and the request has an AWS signature, then only the topic owner and the subscription owner can unsubscribe the endpoint. The unsubscribe action requires AWS authentication. Default: null
Token String Yes Short-lived token sent to an endpoint during the Subscribe action
TopicArn String Yes The ARN of the topic for which you wish to confirm a subscription

Example

subscriptionArn <- "";

// Handle incoming HTTP requests which are sent in response to subscription to confirm said subscription
http.onrequest(function(request, response) {
    try {
        local requestBody = http.jsondecode(request.body);

        // Handle an SNS SubscriptionConfirmation request
        if ("Type" in requestBody && requestBody.Type == AWSSNS_RESPONSES.SUBSCRIPTION_CONFIRMATION) {
            server.log("Received HTTP Request: AWS SNS SubscriptionConfirmation");

            local confirmParams = {
                "Token": requestBody.Token,
                "TopicArn": requestBody.TopicArn
            }

            subscriptionArn = requestBody.TopicArn;

            // Confirm the subscription
            sns.action(AWSSNS_ACTIONS.CONFIRM_SUBSCRIPTION, confirmParams, function(res) {
                server.log("Confirmation Response: " + res.statuscode);

                if (res.statuscode == 200) {
                    // Now that the subscription is established publish a message
                    sns.action(AWSSNS_ACTIONS.PUBLISH, publishParams, function(res) {
                        server.log(" Publish Confirmation XML Response: " + res.body);
                    });
                }
            });
        }

        response.send(200, "OK");
    } catch (exception) {
        server.log("Error handling HTTP request: " + exception);
        response.send(500, "Internal Server Error: " + exception);
    }
});

AWSSNS_ACTIONS.LIST_SUBSCRIPTIONS

Returns an XML list of the requester’s subscriptions as a string in the response table. Please view the AWS SNS documentation for more information.

Action Parameters

Parameter Type Required? Description
NextToken String No Token returned by the previous ListSubscriptions request. Default: null

Example

sns.action(AWSSNS_ACTIONS.LIST_SUBSCRIPTIONS, {}, function (response) {
    // Do something with the returned XML
});

AWSSNS_ACTIONS.LIST_SUBSCRIPTIONS_BY_TOPIC

Returns an XML list of the subscriptions to a specific topic as a string in the response table. Please view the AWS SNS documentation for more information.

Action Parameters

Parameter Type Required? Description
NextToken String No Token returned by the previous ListSubscriptionsByTopic request. Default: null
TopicArn String Yes The ARN of the topic for which you wish to confirm a subscription
Example
// Find the endpoint in the response that corresponds to ARN
local endpointFinder = function (messageBody) {
    local endpoint = http.agenturl();
    local start = messageBody.find(endpoint);
    start += endpoint.len();
    return start;
};

// Finds the SubscriptionArn corresponding to the specified endpoint
local subscriptionFinder = function (messageBody, startIndex) {
    local start = messageBody.find("<SubscriptionArn>", startIndex);
    local finish = messageBody.find("</SubscriptionArn>", startIndex);
    local subscription = messageBody.slice((start + 17), (finish));
    return subscription;
};

local params = {
    "TopicArn": "YOUR_TOPIC_ARN_HERE"
};

sns.action(AWSSNS_ACTIONS.LIST_SUBSCRIPTIONS_BY_TOPIC, params, function (response) {
    // Finds your specific subscription ARN
    local subscriptionArn = subscriptionFinder(response.body, endpointFinder(response.body));
});

AWSSNS_ACTIONS.LIST_TOPICS

Returns an XML list of the requester’s topics as a string in the response table. Please view the AWS SNS documentation for more information.

Action Parameters

Parameter Type Required? Description
NextToken String No Token returned by the previous ListTopics request. Default: null
Example
sns.action(AWSSNS_ACTIONS.LIST_TOPICS, {}, function (response) {
    // Do something the returned XML
})

AWSSNS_ACTIONS.PUBLISH

Sends a message to an Amazon SNS topic or sends a text message (SMS) directly to a phone number. Please view the AWS SNS documentation for more information.

Note You need at least one of the TopicArn, PhoneNumber or TargetArn parameters.

Action Parameters

Parameter Type Required? Description
Message String Yes The message you want to send
MessageAttributes Table No A table of MessageAttributes.entry.N.Name key amd MessageAttributes.entry.N.Value value pairs. For more information, see MessageAttributes Values, below. Default: null
MessageStructure String No Set message structure to JSON if you want to send a different message for each protocol. Default: null
PhoneNumber String No The phone number to which you want to deliver an SMS message. Default: null
Subject String No Optional parameter to be used as the ‘Subject’ line when the message is delivered to email endpoints. Default: null
TargetArn String No Either TopicArn or EndpointArn, but not both. Default: null
TopicArn String No The topic you want to publish to. Default: null

MessageAttributes Values

Key Type Required? Description
BinaryValue Base64-encoded binary data object No Binary type attributes can store any binary, eg. compressed data, encrypted data or images. Default: null
DataType String Yes Amazon SNS supports the following logical data types: String, Number and Binary
StringValue String No Strings are Unicode with UTF8 binary encoding. Default: null

Example

local params = {
    "Message": "Hello World",
    "TopicArn": AWS_SNS_TOPIC_ARN
};

sns.action(AWSSNS_ACTIONS.PUBLISH, params, function (response) {
    // Check the status code (response.statuscode) for a successful publish
});

AWSSNS_ACTIONS.SUBSCRIBE

Prepares to subscribe to an endpoint by sending the endpoint a confirmation message. Please view the AWS SNS documentation for more information.

Action Parameters

Parameter Type Required? Description
Endpoint String No The endpoint that you want to receive notifications. Endpoints vary by protocol
Protocol String Yes The protocol you want to use. Supported protocols include: HTTP, HTTPS, email, email-JSON, SMS, SQS, "application" and lambda
TopicArn String Yes The topic you want to publish to

Example

subscribeParams <- {
    "Protocol": "https",
    "TopicArn": AWS_SNS_TOPIC_ARN,
    "Endpoint": http.agenturl()
};

sns.action(AWSSNS_ACTIONS.SUBSCRIBE, subscribeParams, function (response) {
    server.log("Subscribe Response: " + http.jsonencode(response));
});

AWSSNS_ACTIONS.UNSUBSCRIBE

Deletes a subscription. Please view the AWS SNS documentation for more information.

Action Parameters

Parameter Type Required? Description
SubscriptionArn String Yes The ARN of the subscription to be deleted
Example

See the ConfirmSubscription example to see how to get a value for SubscriptionArn.

local params = {
    "SubscriptionArn": subscriptionArn
};

sns.action(AWSSNS_ACTIONS.UNSUBSCRIBE, params, function(response) {
    server.log("Unsubscribe Response: " + http.jsonencode(response));
});

Callback Response Table

The response table general to all functions contains the following keys:

Key Type Description
body String AWS SNS response in an XML data structure which is received as a string
statuscode Integer An HTTP status code
headers Table See Headers, below

Headers

The headers key’s value is itself a table, with the following keys:

Key Type Description
x-amzn-requestid String The Amazon request ID
content-type String The Content type eg. text/XML
date String The date and time at which the response was sent
content-length String The length of the response content

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
1.0.0 GitHub Convert constants to enums

License

This library is licensed under the MIT License.

© 2023 KORE Wireless. All rights reserved. Terms of Service, Privacy Policy

Toggle