SNS connector - AWS IoT Greengrass

You are viewing the documentation for AWS IoT Greengrass Version 1, which has moved into maintenance mode. If you're new to AWS IoT Greengrass, we strongly recommend that you use AWS IoT Greengrass Version 2, which receives new features, includes all key V1 features, and supports for additional platforms and continuous deployments to large fleets of devices. For more information, see What's new in AWS IoT Greengrass V2 and Move from AWS IoT Greengrass V1 to V2.

SNS connector

The SNS connector publishes messages to an Amazon SNS topic. This enables web servers, email addresses, and other message subscribers to respond to events in the Greengrass group.

This connector receives SNS message information on an MQTT topic, and then sends the message to a specified SNS topic. You can optionally use custom Lambda functions to implement filtering or formatting logic on messages before they are published to this connector.

This connector has the following versions.

Version

ARN

4

arn:aws:greengrass:region::/connectors/SNS/versions/4

3

arn:aws:greengrass:region::/connectors/SNS/versions/3

2

arn:aws:greengrass:region::/connectors/SNS/versions/2

1

arn:aws:greengrass:region::/connectors/SNS/versions/1

For information about version changes, see the Changelog.

Requirements

This connector has the following requirements:

Version 3 - 4
  • AWS IoT Greengrass Core software v1.9.3 or later.

  • Python version 3.7 or 3.8 installed on the core device and added to the PATH environment variable.

    Note

    To use Python 3.8, run the following command to create a symbolic link from the the default Python 3.7 installation folder to the installed Python 3.8 binaries.

    sudo ln -s path-to-python-3.8/python3.8 /usr/bin/python3.7

    This configures your device to meet the Python requirement for AWS IoT Greengrass.

  • A configured SNS topic. For more information, see Creating an Amazon SNS topic in the Amazon Simple Notification Service Developer Guide.

  • The Greengrass group role configured to allow the sns:Publish action on the target Amazon SNStopic, as shown in the following example IAM policy.

    { "Version":"2012-10-17", "Statement":[ { "Sid":"Stmt1528133056761", "Action":[ "sns:Publish" ], "Effect":"Allow", "Resource":[ "arn:aws:sns:region:account-id:topic-name" ] } ] }

    This connector allows you to dynamically override the default topic in the input message payload. If your implementation uses this feature, the IAM policy must allow sns:Publish permission on all target topics. You can grant granular or conditional access to resources (for example, by using a wildcard * naming scheme).

    For the group role requirement, you must configure the role to grant the required permissions and make sure the role has been added to the group. For more information, see Managing the Greengrass group role (console) or Managing the Greengrass group role (CLI).

Versions 1 - 2
  • AWS IoT Greengrass Core software v1.7 or later.

  • Python version 2.7 installed on the core device and added to the PATH environment variable.

  • A configured SNS topic. For more information, see Creating an Amazon SNS topic in the Amazon Simple Notification Service Developer Guide.

  • The Greengrass group role configured to allow the sns:Publish action on the target Amazon SNStopic, as shown in the following example IAM policy.

    { "Version":"2012-10-17", "Statement":[ { "Sid":"Stmt1528133056761", "Action":[ "sns:Publish" ], "Effect":"Allow", "Resource":[ "arn:aws:sns:region:account-id:topic-name" ] } ] }

    This connector allows you to dynamically override the default topic in the input message payload. If your implementation uses this feature, the IAM policy must allow sns:Publish permission on all target topics. You can grant granular or conditional access to resources (for example, by using a wildcard * naming scheme).

    For the group role requirement, you must configure the role to grant the required permissions and make sure the role has been added to the group. For more information, see Managing the Greengrass group role (console) or Managing the Greengrass group role (CLI).

Connector Parameters

This connector provides the following parameters:

Version 4
DefaultSNSArn

The ARN of the default SNS topic to publish messages to. The destination topic can be overridden by the sns_topic_arn property in the input message payload.

Note

The group role must allow sns:Publish permission to all target topics. For more information, see Requirements.

Display name in the AWS IoT console: Default SNS topic ARN

Required: true

Type: string

Valid pattern: arn:aws:sns:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):([a-zA-Z0-9-_]+)$

IsolationMode

The containerization mode for this connector. The default is GreengrassContainer, which means that the connector runs in an isolated runtime environment inside the AWS IoT Greengrass container.

Note

The default containerization setting for the group does not apply to connectors.

Display name in the AWS IoT console: Container isolation mode

Required: false

Type: string

Valid values: GreengrassContainer or NoContainer

Valid pattern: ^NoContainer$|^GreengrassContainer$

Versions 1 - 3
DefaultSNSArn

The ARN of the default SNS topic to publish messages to. The destination topic can be overridden by the sns_topic_arn property in the input message payload.

Note

The group role must allow sns:Publish permission to all target topics. For more information, see Requirements.

Display name in the AWS IoT console: Default SNS topic ARN

Required: true

Type: string

Valid pattern: arn:aws:sns:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):([a-zA-Z0-9-_]+)$

Create Connector Example (AWS CLI)

The following CLI command creates a ConnectorDefinition with an initial version that contains the SNS connector.

aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{ "Connectors": [ { "Id": "MySNSConnector", "ConnectorArn": "arn:aws:greengrass:region::/connectors/SNS/versions/4", "Parameters": { "DefaultSNSArn": "arn:aws:sns:region:account-id:topic-name", "IsolationMode" : "GreengrassContainer" } } ] }'

In the AWS IoT Greengrass console, you can add a connector from the group's Connectors page. For more information, see Getting started with Greengrass connectors (console).

Input data

This connector accepts SNS message information on an MQTT topic, and then publishes the message as is to the target SNS topic. Input messages must be in JSON format.

Topic filter in subscription

sns/message

Message properties
request

Information about the message to send to the SNS topic.

Required: true

Type: object that includes the following properties:

message

The content of the message as a string or in JSON format. For examples, see Example input.

To send JSON, the message_structure property must be set to json and the message must be a string-encoded JSON object that contains a default key.

Required: true

Type: string

Valid pattern: .*

subject

The subject of the message.

Required: false

Type: ASCII text, up to 100 characters. This must begin with a letter, number, or punctuation mark. This must not include line breaks or control characters.

Valid pattern: .*

sns_topic_arn

The ARN of the SNS topic to publish messages to. If specified, the connector publishes to this topic instead of the default topic.

Note

The group role must allow sns:Publish permission to any target topics. For more information, see Requirements.

Required: false

Type: string

Valid pattern: arn:aws:sns:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):([a-zA-Z0-9-_]+)$

message_structure

The structure of the message.

Required: false. This must be specified to send a JSON message.

Type: string

Valid values: json

id

An arbitrary ID for the request. This property is used to map an input request to an output response. When specified, the id property in the response object is set to this value. If you don't use this feature, you can omit this property or specify an empty string.

Required: false

Type: string

Valid pattern: .*

Limits

The message size is bounded by a maximum SNS message size of 256 KB.

Example input: String message

This example sends a string message. It specifies the optional sns_topic_arn property, which overrides the default destination topic.

{ "request": { "subject": "Message subject", "message": "Message data", "sns_topic_arn": "arn:aws:sns:region:account-id:topic2-name" }, "id": "request123" }
Example input: JSON message

This example sends a message as a string encoded JSON object that includes the default key.

{ "request": { "subject": "Message subject", "message": "{ \"default\": \"Message data\" }", "message_structure": "json" }, "id": "request123" }

Output data

This connector publishes status information as output data on an MQTT topic.

Topic filter in subscription

sns/message/status

Example output: Success
{ "response": { "sns_message_id": "f80a81bc-f44c-56f2-a0f0-d5af6a727c8a", "status": "success" }, "id": "request123" }
Example output: Failure
{ "response" : { "error": "InvalidInputException", "error_message": "SNS Topic Arn is invalid", "status": "fail" }, "id": "request123" }

Usage Example

Use the following high-level steps to set up an example Python 3.7 Lambda function that you can use to try out the connector.

Note
  1. Make sure you meet the requirements for the connector.

    For the group role requirement, you must configure the role to grant the required permissions and make sure the role has been added to the group. For more information, see Managing the Greengrass group role (console) or Managing the Greengrass group role (CLI).

  2. Create and publish a Lambda function that sends input data to the connector.

    Save the example code as a PY file. Download and unzip the AWS IoT Greengrass Core SDK for Python. Then, create a zip package that contains the PY file and the greengrasssdk folder at the root level. This zip package is the deployment package that you upload to AWS Lambda.

    After you create the Python 3.7 Lambda function, publish a function version and create an alias.

  3. Configure your Greengrass group.

    1. Add the Lambda function by its alias (recommended). Configure the Lambda lifecycle as long-lived (or "Pinned": true in the CLI).

    2. Add the connector and configure its parameters.

    3. Add subscriptions that allow the connector to receive input data and send output data on supported topic filters.

      • Set the Lambda function as the source, the connector as the target, and use a supported input topic filter.

      • Set the connector as the source, AWS IoT Core as the target, and use a supported output topic filter. You use this subscription to view status messages in the AWS IoT console.

  4. Deploy the group.

  5. In the AWS IoT console, on the Test page, subscribe to the output data topic to view status messages from the connector. The example Lambda function is long-lived and starts sending messages immediately after the group is deployed.

    When you're finished testing, you can set the Lambda lifecycle to on-demand (or "Pinned": false in the CLI) and deploy the group. This stops the function from sending messages.

Example

The following example Lambda function sends an input message to the connector.

import greengrasssdk import time import json iot_client = greengrasssdk.client('iot-data') send_topic = 'sns/message' def create_request_with_all_fields(): return { "request": { "message": "Message from SNS Connector Test" }, "id" : "req_123" } def publish_basic_message(): messageToPublish = create_request_with_all_fields() print("Message To Publish: ", messageToPublish) iot_client.publish(topic=send_topic, payload=json.dumps(messageToPublish)) publish_basic_message() def lambda_handler(event, context): return

Licenses

The SNS connector includes the following third-party software/licensing:

This connector is released under the Greengrass Core Software License Agreement.

Changelog

The following table describes the changes in each version of the connector.

Version

Changes

4

Added the IsolationMode parameter to configure the containerization mode for the connector.

3

Upgraded the Lambda runtime to Python 3.7, which changes the runtime requirement.

2

Fix to reduce excessive logging.

1

Initial release.

A Greengrass group can contain only one version of the connector at a time. For information about upgrading a connector version, see Upgrading connector versions.

See also