Menu
AWS IoT
Developer Guide

CreateTopicRule

Creates a rule. Creating rules is an administrator-level action. Any user who has permission to create rules will be able to access data processed by the rule.

Request syntax:

POST /rules/ruleName Content-type: application/json { "topicRulePayload": { "sql": "string", "description": "string", "actions": [ { "dynamoDB": { "tableName": "string", "roleArn": "string", "operation": "string", "hashKeyField": "string", "hashKeyValue": "string", "hashKeyType": "string", "rangeKeyField": "string", "rangeKeyValue": "string", "rangeKeyType": "string", "payloadField": "string" }, "dynamoDBv2": { "roleArn": "string", "putItem": { "tableName": "string" } }, "lambda": { "functionArn": "string" }, "sns": { "targetArn": "string", "roleArn": "string", "messageFormat": "string" }, "sqs": { "roleArn": "string", "queueUrl": "string", "useBase64": "boolean" }, "kinesis": { "roleArn": "string", "streamName": "string", "partitionKey": "string" }, "republish": { "roleArn": "string", "topic": "string" }, "s3": { "roleArn": "string", "bucketName": "string", "key": "string", "cannedAcl": "string" }, "firehose": { "roleArn": "string", "deliveryStreamName": "string", "separator": "string" }, "cloudwatchMetric": { "roleArn": "string", "metricNamespace": "string", "metricName": "string", "metricValue": "string", "metricUnit": "string", "metricTimestamp": "string" }, "cloudwatchAlarm": { "roleArn": "string", "alarmName": "string", "stateReason": "string", "stateValue": "string" }, "elasticsearch": { "roleArn": "string", "endpoint": "string", "index": "string", "type": "string", "id": "string" }, "salesforce": { "token": "string", "url": "string" } } ], "ruleDisabled": "boolean", "awsIotSqlVersion": "string", "errorAction": { "dynamoDB": { "tableName": "string", "roleArn": "string", "operation": "string", "hashKeyField": "string", "hashKeyValue": "string", "hashKeyType": "string", "rangeKeyField": "string", "rangeKeyValue": "string", "rangeKeyType": "string", "payloadField": "string" }, "dynamoDBv2": { "roleArn": "string", "putItem": { "tableName": "string" } }, "lambda": { "functionArn": "string" }, "sns": { "targetArn": "string", "roleArn": "string", "messageFormat": "string" }, "sqs": { "roleArn": "string", "queueUrl": "string", "useBase64": "boolean" }, "kinesis": { "roleArn": "string", "streamName": "string", "partitionKey": "string" }, "republish": { "roleArn": "string", "topic": "string" }, "s3": { "roleArn": "string", "bucketName": "string", "key": "string", "cannedAcl": "string" }, "firehose": { "roleArn": "string", "deliveryStreamName": "string", "separator": "string" }, "cloudwatchMetric": { "roleArn": "string", "metricNamespace": "string", "metricName": "string", "metricValue": "string", "metricUnit": "string", "metricTimestamp": "string" }, "cloudwatchAlarm": { "roleArn": "string", "alarmName": "string", "stateReason": "string", "stateValue": "string" }, "elasticsearch": { "roleArn": "string", "endpoint": "string", "index": "string", "type": "string", "id": "string" }, "salesforce": { "token": "string", "url": "string" } } } }

URI Request Parameters:

Name

Type

Req?

Description

ruleName

RuleName

yes

The name of the rule.

Request Body Parameters:

Name

Type

Req?

Description

topicRulePayload

TopicRulePayload

yes

The rule payload.

Errors:

SqlParseException

The Rule-SQL expression can't be parsed correctly.

HTTP response code: 400

InternalException

An unexpected error has occurred.

HTTP response code: 500

InvalidRequestException

The contents of the request were invalid. For example, this code is returned when an UpdateJobExecution request contains invalid status details. The message contains details about the error.

HTTP response code: 400

ResourceAlreadyExistsException

The resource already exists.

HTTP response code: 409

ServiceUnavailableException

The service is temporarily unavailable.

HTTP response code: 503

CLI

Synopsis:

aws iot create-topic-rule \ --rule-name <value> \ --topic-rule-payload <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "ruleName": "string", "topicRulePayload": { "sql": "string", "description": "string", "actions": [ { "dynamoDB": { "tableName": "string", "roleArn": "string", "operation": "string", "hashKeyField": "string", "hashKeyValue": "string", "hashKeyType": "string", "rangeKeyField": "string", "rangeKeyValue": "string", "rangeKeyType": "string", "payloadField": "string" }, "dynamoDBv2": { "roleArn": "string", "putItem": { "tableName": "string" } }, "lambda": { "functionArn": "string" }, "sns": { "targetArn": "string", "roleArn": "string", "messageFormat": "string" }, "sqs": { "roleArn": "string", "queueUrl": "string", "useBase64": "boolean" }, "kinesis": { "roleArn": "string", "streamName": "string", "partitionKey": "string" }, "republish": { "roleArn": "string", "topic": "string" }, "s3": { "roleArn": "string", "bucketName": "string", "key": "string", "cannedAcl": "string" }, "firehose": { "roleArn": "string", "deliveryStreamName": "string", "separator": "string" }, "cloudwatchMetric": { "roleArn": "string", "metricNamespace": "string", "metricName": "string", "metricValue": "string", "metricUnit": "string", "metricTimestamp": "string" }, "cloudwatchAlarm": { "roleArn": "string", "alarmName": "string", "stateReason": "string", "stateValue": "string" }, "elasticsearch": { "roleArn": "string", "endpoint": "string", "index": "string", "type": "string", "id": "string" }, "salesforce": { "token": "string", "url": "string" } } ], "ruleDisabled": "boolean", "awsIotSqlVersion": "string", "errorAction": { "dynamoDB": { "tableName": "string", "roleArn": "string", "operation": "string", "hashKeyField": "string", "hashKeyValue": "string", "hashKeyType": "string", "rangeKeyField": "string", "rangeKeyValue": "string", "rangeKeyType": "string", "payloadField": "string" }, "dynamoDBv2": { "roleArn": "string", "putItem": { "tableName": "string" } }, "lambda": { "functionArn": "string" }, "sns": { "targetArn": "string", "roleArn": "string", "messageFormat": "string" }, "sqs": { "roleArn": "string", "queueUrl": "string", "useBase64": "boolean" }, "kinesis": { "roleArn": "string", "streamName": "string", "partitionKey": "string" }, "republish": { "roleArn": "string", "topic": "string" }, "s3": { "roleArn": "string", "bucketName": "string", "key": "string", "cannedAcl": "string" }, "firehose": { "roleArn": "string", "deliveryStreamName": "string", "separator": "string" }, "cloudwatchMetric": { "roleArn": "string", "metricNamespace": "string", "metricName": "string", "metricValue": "string", "metricUnit": "string", "metricTimestamp": "string" }, "cloudwatchAlarm": { "roleArn": "string", "alarmName": "string", "stateReason": "string", "stateValue": "string" }, "elasticsearch": { "roleArn": "string", "endpoint": "string", "index": "string", "type": "string", "id": "string" }, "salesforce": { "token": "string", "url": "string" } } } }

cli-input-json fields:

Name

Type

Description

ruleName

string

length max:128 min:1

pattern: ^[a-zA-Z0-9_]+$

The name of the rule.

topicRulePayload

TopicRulePayload

The rule payload.

sql

string

The SQL statement used to query the topic. For more information, see AWS IoT SQL Reference in the AWS IoT Developer Guide.

description

string

The description of the rule.

actions

list

member: Action

The actions associated with the rule.

Action

Action

dynamoDB

DynamoDBAction

Write to a DynamoDB table.

tableName

string

The name of the DynamoDB table.

roleArn

string

The ARN of the IAM role that grants access to the DynamoDB table.

operation

string

The type of operation to be performed. This follows the substitution template, so it can be $ operation, but the substitution must result in one of the following: INSERT, UPDATE, or DELETE.

hashKeyField

string

The hash key name.

hashKeyValue

string

The hash key value.

hashKeyType

string

enum: STRING | NUMBER

java class: iot.goldeneye.service.DynamoKeyType

The hash key type. Valid values are "STRING" or "NUMBER"

rangeKeyField

string

The range key name.

rangeKeyValue

string

The range key value.

rangeKeyType

string

enum: STRING | NUMBER

java class: iot.goldeneye.service.DynamoKeyType

The range key type. Valid values are "STRING" or "NUMBER"

payloadField

string

The action payload. This name can be customized.

dynamoDBv2

DynamoDBv2Action

Write to a DynamoDB table. This is a new version of the DynamoDB action. It allows you to write each attribute in an MQTT message payload into a separate DynamoDB column.

roleArn

string

The ARN of the IAM role that grants access to the DynamoDB table.

putItem

PutItemInput

Specifies the DynamoDB table to which the message data will be written. For example:

{ "dynamoDBv2": { "roleArn": "aws:iam:12341251:my-role" "putItem": { "tableName": "my-table" } } }

Each attribute in the message payload will be written to a separate column in the DynamoDB database.

tableName

string

The table where the message data will be written

lambda

LambdaAction

Invoke a Lambda function.

functionArn

string

The ARN of the Lambda function.

sns

SnsAction

Publish to an Amazon SNS topic.

targetArn

string

The ARN of the SNS topic.

roleArn

string

The ARN of the IAM role that grants access.

messageFormat

string

enum: RAW | JSON

java class: iot.goldeneye.service.MessageFormat

The message format of the message to publish. Optional. Accepted values are "JSON" and "RAW". The default value of the attribute is "RAW". SNS uses this setting to determine if the payload should be parsed and relevant platform-specific bits of the payload should be extracted. To read more about SNS message formats, see http://docs.aws.amazon.com/sns/latest/dg/json-formats.html refer to their official documentation.

sqs

SqsAction

Publish to an Amazon SQS queue.

roleArn

string

The ARN of the IAM role that grants access.

queueUrl

string

The URL of the Amazon SQS queue.

useBase64

boolean

java class: java.lang.Boolean

Specifies whether to use Base64 encoding.

kinesis

KinesisAction

Write data to an Amazon Kinesis stream.

roleArn

string

The ARN of the IAM role that grants access to the Amazon Kinesis stream.

streamName

string

The name of the Amazon Kinesis stream.

partitionKey

string

The partition key.

republish

RepublishAction

Publish to another MQTT topic.

roleArn

string

The ARN of the IAM role that grants access.

topic

string

The name of the MQTT topic.

s3

S3Action

Write to an Amazon S3 bucket.

roleArn

string

The ARN of the IAM role that grants access.

bucketName

string

The Amazon S3 bucket.

key

string

The object key.

cannedAcl

string

enum: private | public-read | public-read-write | aws-exec-read | authenticated-read | bucket-owner-read | bucket-owner-full-control | log-delivery-write

java class: iot.goldeneye.service.CannedAccessControlList

The Amazon S3 canned ACL that controls access to the object identified by the object key. For more information, see S3 canned ACLs.

firehose

FirehoseAction

Write to an Amazon Kinesis Firehose stream.

roleArn

string

The IAM role that grants access to the Amazon Kinesis Firehose stream.

deliveryStreamName

string

The delivery stream name.

separator

string

pattern: ([ ])|( )|(,)

A character separator that will be used to separate records written to the Firehose stream. Valid values are: '\n' (newline), '\t' (tab), '\r\n' (Windows newline), ',' (comma).

cloudwatchMetric

CloudwatchMetricAction

Capture a CloudWatch metric.

roleArn

string

The IAM role that allows access to the CloudWatch metric.

metricNamespace

string

The CloudWatch metric namespace name.

metricName

string

The CloudWatch metric name.

metricValue

string

The CloudWatch metric value.

metricUnit

string

The metric unit supported by CloudWatch.

metricTimestamp

string

An optional Unix timestamp.

cloudwatchAlarm

CloudwatchAlarmAction

Change the state of a CloudWatch alarm.

roleArn

string

The IAM role that allows access to the CloudWatch alarm.

alarmName

string

The CloudWatch alarm name.

stateReason

string

The reason for the alarm change.

stateValue

string

The value of the alarm state. Acceptable values are: OK, ALARM, INSUFFICIENT_DATA.

elasticsearch

ElasticsearchAction

Write data to an Amazon Elasticsearch Service domain.

roleArn

string

The IAM role ARN that has access to Elasticsearch.

endpoint

string

pattern: https?://.*

The endpoint of your Elasticsearch domain.

index

string

The Elasticsearch index where you want to store your data.

type

string

The type of document you are storing.

id

string

The unique identifier for the document you are storing.

salesforce

SalesforceAction

Send a message to a Salesforce IoT Cloud Input Stream.

token

string

length min:40

The token used to authenticate access to the Salesforce IoT Cloud Input Stream. The token is available from the Salesforce IoT Cloud platform after creation of the Input Stream.

url

string

length max:2000

pattern: https://ingestion-[a-zA-Z0-9]{1,12}.[a-zA-Z0-9]+.((sfdc-matrix.net)|(sfdcnow.com))/streams/w 1,20/w 1,20/event

The URL exposed by the Salesforce IoT Cloud Input Stream. The URL is available from the Salesforce IoT Cloud platform after creation of the Input Stream.

ruleDisabled

boolean

java class: java.lang.Boolean

Specifies whether the rule is disabled.

awsIotSqlVersion

string

The version of the SQL rules engine to use when evaluating the rule.

errorAction

Action

The action to take when an error occurs.

dynamoDB

DynamoDBAction

Write to a DynamoDB table.

tableName

string

The name of the DynamoDB table.

roleArn

string

The ARN of the IAM role that grants access to the DynamoDB table.

operation

string

The type of operation to be performed. This follows the substitution template, so it can be $ operation, but the substitution must result in one of the following: INSERT, UPDATE, or DELETE.

hashKeyField

string

The hash key name.

hashKeyValue

string

The hash key value.

hashKeyType

string

enum: STRING | NUMBER

java class: iot.goldeneye.service.DynamoKeyType

The hash key type. Valid values are "STRING" or "NUMBER"

rangeKeyField

string

The range key name.

rangeKeyValue

string

The range key value.

rangeKeyType

string

enum: STRING | NUMBER

java class: iot.goldeneye.service.DynamoKeyType

The range key type. Valid values are "STRING" or "NUMBER"

payloadField

string

The action payload. This name can be customized.

dynamoDBv2

DynamoDBv2Action

Write to a DynamoDB table. This is a new version of the DynamoDB action. It allows you to write each attribute in an MQTT message payload into a separate DynamoDB column.

roleArn

string

The ARN of the IAM role that grants access to the DynamoDB table.

putItem

PutItemInput

Specifies the DynamoDB table to which the message data will be written. For example:

{ "dynamoDBv2": { "roleArn": "aws:iam:12341251:my-role" "putItem": { "tableName": "my-table" } } }

Each attribute in the message payload will be written to a separate column in the DynamoDB database.

tableName

string

The table where the message data will be written

lambda

LambdaAction

Invoke a Lambda function.

functionArn

string

The ARN of the Lambda function.

sns

SnsAction

Publish to an Amazon SNS topic.

targetArn

string

The ARN of the SNS topic.

roleArn

string

The ARN of the IAM role that grants access.

messageFormat

string

enum: RAW | JSON

java class: iot.goldeneye.service.MessageFormat

The message format of the message to publish. Optional. Accepted values are "JSON" and "RAW". The default value of the attribute is "RAW". SNS uses this setting to determine if the payload should be parsed and relevant platform-specific bits of the payload should be extracted. To read more about SNS message formats, see http://docs.aws.amazon.com/sns/latest/dg/json-formats.html refer to their official documentation.

sqs

SqsAction

Publish to an Amazon SQS queue.

roleArn

string

The ARN of the IAM role that grants access.

queueUrl

string

The URL of the Amazon SQS queue.

useBase64

boolean

java class: java.lang.Boolean

Specifies whether to use Base64 encoding.

kinesis

KinesisAction

Write data to an Amazon Kinesis stream.

roleArn

string

The ARN of the IAM role that grants access to the Amazon Kinesis stream.

streamName

string

The name of the Amazon Kinesis stream.

partitionKey

string

The partition key.

republish

RepublishAction

Publish to another MQTT topic.

roleArn

string

The ARN of the IAM role that grants access.

topic

string

The name of the MQTT topic.

s3

S3Action

Write to an Amazon S3 bucket.

roleArn

string

The ARN of the IAM role that grants access.

bucketName

string

The Amazon S3 bucket.

key

string

The object key.

cannedAcl

string

enum: private | public-read | public-read-write | aws-exec-read | authenticated-read | bucket-owner-read | bucket-owner-full-control | log-delivery-write

java class: iot.goldeneye.service.CannedAccessControlList

The Amazon S3 canned ACL that controls access to the object identified by the object key. For more information, see S3 canned ACLs.

firehose

FirehoseAction

Write to an Amazon Kinesis Firehose stream.

roleArn

string

The IAM role that grants access to the Amazon Kinesis Firehose stream.

deliveryStreamName

string

The delivery stream name.

separator

string

pattern: ([ ])|( )|(,)

A character separator that will be used to separate records written to the Firehose stream. Valid values are: '\n' (newline), '\t' (tab), '\r\n' (Windows newline), ',' (comma).

cloudwatchMetric

CloudwatchMetricAction

Capture a CloudWatch metric.

roleArn

string

The IAM role that allows access to the CloudWatch metric.

metricNamespace

string

The CloudWatch metric namespace name.

metricName

string

The CloudWatch metric name.

metricValue

string

The CloudWatch metric value.

metricUnit

string

The metric unit supported by CloudWatch.

metricTimestamp

string

An optional Unix timestamp.

cloudwatchAlarm

CloudwatchAlarmAction

Change the state of a CloudWatch alarm.

roleArn

string

The IAM role that allows access to the CloudWatch alarm.

alarmName

string

The CloudWatch alarm name.

stateReason

string

The reason for the alarm change.

stateValue

string

The value of the alarm state. Acceptable values are: OK, ALARM, INSUFFICIENT_DATA.

elasticsearch

ElasticsearchAction

Write data to an Amazon Elasticsearch Service domain.

roleArn

string

The IAM role ARN that has access to Elasticsearch.

endpoint

string

pattern: https?://.*

The endpoint of your Elasticsearch domain.

index

string

The Elasticsearch index where you want to store your data.

type

string

The type of document you are storing.

id

string

The unique identifier for the document you are storing.

salesforce

SalesforceAction

Send a message to a Salesforce IoT Cloud Input Stream.

token

string

length min:40

The token used to authenticate access to the Salesforce IoT Cloud Input Stream. The token is available from the Salesforce IoT Cloud platform after creation of the Input Stream.

url

string

length max:2000

pattern: https://ingestion-[a-zA-Z0-9]{1,12}.[a-zA-Z0-9]+.((sfdc-matrix.net)|(sfdcnow.com))/streams/w 1,20/w 1,20/event

The URL exposed by the Salesforce IoT Cloud Input Stream. The URL is available from the Salesforce IoT Cloud platform after creation of the Input Stream.

Output:

None

On this page: