Creating an AWS IoT rule

You can create AWS IoT rules to route data from your connected things to interact with other AWS services. An AWS IoT rule consists of the following components:

Before you create an AWS IoT rule, you must create an IAM role with a policy that allows access to the required AWS resources. AWS IoT assumes this role when implementing a rule. For more information, see Granting an AWS IoT rule the access it requires and Passing role permissions.

When you create a rule, be aware of how much data you're publishing on topics. If you create rules that include a wildcard topic pattern, they might match a large percentage of your messages. If this is the case, you might need to increase the capacity of the AWS resources used by the target actions. Also, if you create a republish rule that includes a wildcard topic pattern, you can end up with a circular rule that causes an infinite loop.

Create a rule (Console)

After you create a rule successfully, you will see the rule listed on the Rules page. You can select a rule to open the Details page where you can view a rule, edit a rule, deactivate a rule, and delete a rule.

Create a rule (CLI)

To create a rule (AWS CLI)

Use the create-topic-rule command to create a rule:

aws iot create-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json

The following is an example payload file with a rule that inserts all messages sent to the iot/test topic into the specified DynamoDB table. The SQL statement filters the messages and the role ARN grants AWS IoT permission to write to the DynamoDB table.

{
	"sql": "SELECT * FROM 'iot/test'",
	"ruleDisabled": false,
	"awsIotSqlVersion": "2016-03-23",
	"actions": [
		{
			"dynamoDB": {
				"tableName": "my-dynamodb-table",
				"roleArn": "arn:aws:iam::123456789012:role/my-iot-role",
				"hashKeyField": "topic",
				"hashKeyValue": "${topic(2)}",
				"rangeKeyField": "timestamp",
				"rangeKeyValue": "${timestamp()}"
			}
		}
	]
}

The following is an example payload file with a rule that inserts all messages sent to the iot/test topic into the specified S3 bucket. The SQL statement filters the messages, and the role ARN grants AWS IoT permission to write to the Amazon S3 bucket.

{
	"awsIotSqlVersion": "2016-03-23",
	"sql": "SELECT * FROM 'iot/test'",
	"ruleDisabled": false,
	"actions": [
		{
			"s3": {
				"roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3",
				"bucketName": "amzn-s3-demo-bucket",
				"key": "myS3Key"
			}
		}
	]
} 

The following is an example payload file with a rule that pushes data to Amazon OpenSearch Service:

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

The following is an example payload file with a rule that invokes a Lambda function:

{
	"sql": "expression",
	"ruleDisabled": false,
	"awsIotSqlVersion": "2016-03-23",
	"actions": [
		{
			"lambda": {
				"functionArn": "arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function"
			}
		}
	]
}

The following is an example payload file with a rule that publishes to an Amazon SNS topic:

{
	"sql": "expression",
	"ruleDisabled": false,
	"awsIotSqlVersion": "2016-03-23",
	"actions": [
		{
			"sns": {
				"targetArn": "arn:aws:sns:us-west-2:123456789012:my-sns-topic",
				"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
			}
		}
	]
}

The following is an example payload file with a rule that republishes on a different MQTT topic:

{
	"sql": "expression",
	"ruleDisabled": false,
	"awsIotSqlVersion": "2016-03-23",
	"actions": [
		{
			"republish": {
				"topic": "my-mqtt-topic",
				"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
			}
		}
	]
}

The following is an example payload file with a rule that pushes data to an Amazon Data Firehose stream:

{
	"sql": "SELECT * FROM 'my-topic'",
	"ruleDisabled": false,
	"awsIotSqlVersion": "2016-03-23",
	"actions": [
		{
			"firehose": {
				"roleArn": "arn:aws:iam::123456789012:role/my-iot-role",
				"deliveryStreamName": "my-stream-name"
			}
		}
	]
}

The following is an example payload file with a rule that uses the Amazon SageMaker AI machinelearning_predict function to republish to a topic if the data in the MQTT payload is classified as a 1.

{
	"sql": "SELECT * FROM 'iot/test' where machinelearning_predict('my-model', 'arn:aws:iam::123456789012:role/my-iot-aml-role', *).predictedLabel=1",
	"ruleDisabled": false,
	"awsIotSqlVersion": "2016-03-23",
	"actions": [
		{
			"republish": {
				"roleArn": "arn:aws:iam::123456789012:role/my-iot-role",
				"topic": "my-mqtt-topic"
			}
		}
	]
}

The following is an example payload file with a rule that publishes messages to a Salesforce IoT Cloud input stream.

{
	"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"
			}
		}
	]
}

The following is an example payload file with a rule that starts an execution of a Step Functions state machine.

{
	"sql": "expression",
	"ruleDisabled": false,
	"awsIotSqlVersion": "2016-03-23",
	"actions": [
		{
			"stepFunctions": {
				"stateMachineName": "myCoolStateMachine",
				"executionNamePrefix": "coolRunning",
				"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
			}
		}
	]
}