AWS IoT Rule Actions

When creating an AWS IoT rule with a CloudWatch alarm action, you must specify the following information:

The following JSON example shows how to define a CloudWatch alarm action in an AWS IoT rule:

{
    "topicRulePayload": {
        "sql": "SELECT * FROM 'some/topic'", 
        "ruleDisabled": false, 
        "awsIotSqlVersion": "2016-03-23",
        "actions": [{
            "cloudwatchAlarm": {
                "roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw", 
                "alarmName": "IotAlarm", 
                "stateReason": "Temperature stabilized.",
                "stateValue": "OK"
            }
        }]
    }
}

For more information, see CloudWatch Alarms.

When creating an AWS IoT rule with a CloudWatch metric action, you must specify the following information:

The following JSON example shows how to define a CloudWatch metric action in an AWS IoT rule:

{
    "topicRulePayload": {
        "sql": "SELECT * FROM 'some/topic'", 
        "ruleDisabled": false, 
        "awsIotSqlVersion": "2016-03-23",
        "actions": [{
            "cloudwatchMetric": {
                "roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw", 
                "metricNamespace": "IotNamespace", 
                "metricName": "IotMetric",
                "metricValue": "1",
                "metricUnit": "Count",
                "metricTimestamp": "1456821314"
            }
        }]
    }
}

For more information, see CloudWatch Metrics.

When creating a DynamoDB rule, you must specify the following information:

The data written to the DynamoDB table is the result from the SQL statement of the rule. The hashKeyValue and rangeKeyValue fields are usually composed of expressions (for example, "${topic()}" or "${timestamp()}").

The following JSON example shows how to define a dynamoDB action in an AWS IoT rule:

{
    "topicRulePayload": {
        "ruleDisabled": false, 
        "sql": "SELECT * AS message FROM 'some/topic'", 
        "description": "A test Dynamo DB rule", 
        "awsIotSqlVersion": "2016-03-23",
        "actions": [{
            "dynamoDB": {
                "hashKeyField": "key", 
                "roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDB", 
                 "tableName": "my_ddb_table", 
                 "hashKeyValue": "${topic()}", 
                 "rangeKeyValue": "${timestamp()}", 
                 "rangeKeyField": "timestamp"
             }
        }]
    }
}

For more information, see the Amazon DynamoDB Getting Started Guide.

When creating a DynamoDB rule, you must specify the following information:

The data written to the DynamoDB table is the result from the SQL statement of the rule.

The following JSON example shows how to define a dynamoDB action in an AWS IoT rule:

{
    "topicRulePayload": {
        "sql": "SELECT * AS message FROM 'some/topic'", 
        "ruleDisabled": false, 
        "description": "A test DynamoDBv2 rule", 
        "awsIotSqlVersion": "2016-03-23",
        "actions": [{
            "dynamoDBv2": {
                "roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDBv2", 
                "putItem": {
                    "tableName": "my_ddb_table"
                }
             }
        }]
    }
}

For more information, see the Amazon DynamoDB Getting Started Guide.

When you create an AWS IoT rule with an elasticsearch action, you must specify the following information:

The following JSON example shows how to define an elasticsearch action in an AWS IoT rule:

{
  "topicRulePayload":{
    "sql":"SELECT *, timestamp() as timestamp FROM 'iot/test'",
    "ruleDisabled":false,
    "awsIotSqlVersion": "2016-03-23",
    "actions":[{
        "elasticsearch":{
          "roleArn":"arn:aws:iam::123456789012:role/aws_iot_es",
          "endpoint":"https://my-endpoint",
          "index":"my-index",
          "type":"my-type",
          "id":"${newuuid()}"
        }
    }]
  }
}

For more information, see the Amazon Elasticsearch Service Developer Guide.

When creating a rule with a firehose action, you must specify the following information:

The following JSON example shows how to create an AWS IoT rule with a firehose action:

{
    "topicRulePayload": {
        "sql": "SELECT * FROM 'some/topic'", 
        "ruleDisabled": false, 
        "awsIotSqlVersion": "2016-03-23",
        "actions": [{
            "firehose": {
                "roleArn": "arn:aws:iam::123456789012:role/aws_iot_firehose", 
                "deliveryStreamName": "my_firehose_stream"
            }
        }] 
    }
}

For more information, see the Kinesis Data Firehose Developer Guide.

When creating a rule with an iotAnalytics action, you must specify the following information:

The policy attached to the role you specify should look like this:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "iotanalytics:BatchPutMessage",
            "Resource": [
                "arn:aws:iotanalytics:us-west-2:<your-account-number>:channel/mychannel"
            ]
        }
    ]
}

and have a trust relationship that looks like this:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "iot.amazonaws.com"
            },
            "Action": "sts:AssumeRole",
        }
    ]
}

The following JSON example shows how to create an AWS IoT rule with an iotAnalytics action:

{
    "topicRulePayload": {
        "sql": "SELECT * FROM 'some/topic'", 
        "ruleDisabled": false, 
        "awsIotSqlVersion": "2016-03-23",
        "actions": [{
            "iotAnalytics": {
                "channelName": "mychannel", 
                "roleArn": "arn:aws:iam::123456789012:role/analyticsRole", 
            }
        }]
    }
}

For more information, see the AWS IoT Analytics User Guide.

The AWS IoT Analytics console also has a Quick start feature that allows you to create a channel, data store, pipeline, and data store with one click. Look for this page when you enter the AWS IoT Analytics console:

When creating a rule with a iotEvents action, you must specify the following information:

The following JSON example shows how to create an AWS IoT rule with an iotEvents action:

{
    "topicRulePayload": {
      "sql": "expression",
      "ruleDisabled": false,
      "description": "An AWS IoT Events test rule",
      "awsIotSqlVersion": "2016-03-23",
      "actions": [{
          "iotEvents": {
            "inputName": "MyIoTEventsInput",
            "messageId": "1234567890",
            "roleArn": "arn:aws:iam::123456789012:role/aws_iot_events"
          },
      }]
    }
}

For more information, see the AWS IoT Events Developer Guide.

When creating an AWS IoT rule with a kinesis action, you must specify the following information:

The following JSON example shows how to define a kinesis action in an AWS IoT rule:

{
    "topicRulePayload": {
        "sql": "SELECT * FROM 'some/topic'", 
        "ruleDisabled": false, 
        "awsIotSqlVersion": "2016-03-23",
        "actions": [{
            "kinesis": {
                "roleArn": "arn:aws:iam::123456789012:role/aws_iot_kinesis", 
                "streamName": "my_kinesis_stream", 
                "partitionKey": "${topic()}"
            }
        }], 
    }
}

For more information, see the Kinesis Developer Guide.

In order for AWS IoT to call a Lambda function, you must configure a policy granting the lambda:InvokeFunction permission to AWS IoT. Lambda functions use resource-based policies, so you must attach the policy to the Lambda function itself. Use the following CLI command to attach a policy granting lambda:InvokeFunction permission:

aws lambda add-permission --function-name "function_name" --region "region" --principal iot.amazonaws.com --source-arn arn:aws:iot:us-east-2:account_id:rule/rule_name --source-account "account_id" --statement-id "unique_id" --action "lambda:InvokeFunction"

The following are the arguments for the add-permission command:

For more information, see Lambda Permission Model.

When creating a rule with a lambda action, you must specify the Lambda function to invoke when the rule is triggered.

The following JSON example shows a rule that calls a Lambda function:

{
    "topicRulePayload": {
        "sql": "SELECT * FROM 'some/topic'", 
        "ruleDisabled": false, 
        "awsIotSqlVersion": "2016-03-23",
        "actions": [{
            "lambda": {
                "functionArn": "arn:aws:lambda:us-east-2:123456789012:function:myLambdaFunction"
             }
        }]
    }
}

If you do not specify a version or alias for your Lambda function, the most recent version of the function is executed. You can specify a version or alias if you want to execute a specific version of your Lambda function. To specify a version or alias, append the version or alias to the ARN of the Lambda function. For example:

"arn:aws:lambda:us-east-2:123456789012:function:myLambdaFunction:someAlias"

For more information about versioning and aliases see AWS Lambda Function Versioning and Aliases. For more information about AWS Lambda, see the AWS Lambda Developer Guide.

When creating a rule with a republish action, you must specify the following information:

{
    "topicRulePayload": {
        "sql": "SELECT * FROM 'some/topic'", 
        "ruleDisabled": false, 
        "awsIotSqlVersion": "2016-03-23",
        "actions": [{
            "republish": {
                "topic": "another/topic", 
                "roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish",
                "qos": 1
            }
        }]
    }
}

When creating an AWS IoT rule with an s3 action, you must specify the following information, except cannedacl, which is optional:

The following JSON example shows how to define an s3 action in an AWS IoT rule:

{
    "topicRulePayload": {
        "sql": "SELECT * FROM 'some/topic'", 
        "ruleDisabled": false, 
        "awsIotSqlVersion": "2016-03-23",
        "actions": [{
            "s3": {
                "roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3", 
                "bucketName": "my-bucket", 
                "key": "${topic()}/${timestamp()}"
                "cannedacl": "public-read"
            }
        }]
    }
}

For more information, see the Amazon S3 Developer Guide.

When creating a rule with a salesforce action, you must specify the following information:

The following JSON example shows how to create an AWS IoT rule with a salesforce action:

{
    "topicRulePayload": {
      "sql": "expression",
      "ruleDisabled": false,
      "awsIotSqlVersion": "2016-03-23",
      "actions": [{
          "salesforce": {
              "token": "ABCDEFGHI123456789abcdefghi123456789",
              "url": "https://ingestion-cluster-id.my-env.sfdcnow.com/streams/stream-id/connection-id/my-event"
          }
      }]
    }
}

For more information, refer to the Salesforce IoT documentation.

When creating a rule with an sns action, you must specify the following information:

The following JSON example shows how to define an sns action in an AWS IoT rule:

{
    "topicRulePayload": {
        "sql": "SELECT * FROM 'some/topic'", 
        "ruleDisabled": false, 
        "awsIotSqlVersion": "2016-03-23",
        "actions": [{
            "sns": {
                "targetArn": "arn:aws:sns:us-east-2:123456789012:my_sns_topic", 
                "roleArn": "arn:aws:iam::123456789012:role/aws_iot_sns"
            }
        }]
    }
}

For more information, see the Amazon SNS Developer Guide.

When creating a rule with an sqs action, you must specify the following information:

The following JSON example shows how to create an AWS IoT rule with an sqs action:

{
    "topicRulePayload": {
        "sql": "SELECT * FROM 'some/topic'", 
        "ruleDisabled": false, 
        "awsIotSqlVersion": "2016-03-23",
        "actions": [{
            "sqs": {
                "queueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/my_sqs_queue", 
                "roleArn": "arn:aws:iam::123456789012:role/aws_iot_sqs", 
                "useBase64": false
            }
        }]
    }
}

SQS action does not support SQS FIFO Queues. Because the Rules Engine is a fully distributed service, there is no guarantee of message order when the SQS action is triggered.

For more information, see the Amazon SQS Developer Guide.

When creating a rule with a stepFunctions action, you must specify the following information:

The following JSON example shows how to create an AWS IoT rule with a stepFunctions action:

{
    "topicRulePayload": {
      "sql": "expression",
      "ruleDisabled": false,
      "description": "A step functions test rule",
      "awsIotSqlVersion": "2016-03-23",
      "actions": [{
          "stepFunctions": {
              "executionNamePrefix": "myExecution",
              "stateMachineName": "myStateMachine",
              "roleArn": "arn:aws:iam::123456789012:role/aws_iot_step_functions"
          }
      }]
    }
}

For more information, see the Step Functions Developer Guide.