AWS IoT
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 Amazon AWS 入门

AWS IoT 规则操作

AWS IoT 规则操作用于指定规则触发后应执行的操作。您可以定义一些操作以便将数据写入 DynamoDB 数据库或 Kinesis 流,或者调用 Lambda 函数等。支持以下操作:

  • cloudwatchAlarm – 更改 CloudWatch 警报。

  • cloudwatchMetric – 捕获 CloudWatch 指标。

  • dynamoDB – 将数据写入 DynamoDB 数据库。

  • dynamoDBv2 – 将数据写入 DynamoDB 数据库。

  • elasticsearch – 将数据写入 Amazon Elasticsearch Service 域。

  • firehose – 将数据写入 Amazon Kinesis Data Firehose 流。

  • iotAnalytics 向 AWS IoT Analytics 通道发送数据。

  • kinesis – 将数据写入 Kinesis 流。

  • lambda – 调用 Lambda 函数。

  • republish - 在另一个 MQTT 主题上重新发布消息。

  • s3 – 将数据写入 Amazon S3 存储桶。

  • salesforce - 将消息写入 Salesforce IoT 输入流。

  • sns - 将数据编写为推送通知。

  • sqs - 将数据写入 SQS 队列。

  • stepFunctions – 开始执行 Step Functions 状态机。

注意

AWS IoT 规则引擎当前不支持重新尝试传输未能发布到另一个服务的消息。

以下部分将详细讨论每项操作。

CloudWatch 警报操作

CloudWatch Alarm Actionmore info (1)
CloudWatch Alarm Action

通过 CloudWatch 警报操作,您可以更改 CloudWatch 警报状态。您可以在此调用中指定状态更改原因和状态值。

more info (1)

使用 AWS IoT 警报操作创建 CloudWatch 规则时,您必须指定以下信息:

roleArn

允许访问 IAM 警报的 CloudWatch 角色。

alarmName

CloudWatch 警报名称。

stateReason

警报更改的原因。

stateValue

警报状态的值。可接受的值包括 OKALARMINSUFFICIENT_DATA

注意

确保与规则关联的角色拥有授予 cloudwatch:SetAlarmState 权限的策略。

下面的 JSON 示例介绍了如何在 CloudWatch 规则中定义 AWS IoT 警报操作:

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

有关更多信息,请参阅 CloudWatch 警报

CloudWatch 指标操作

CloudWatch Metric Actionmore info (2)
CloudWatch Metric Action

通过 CloudWatch 指标操作,您可以捕获 CloudWatch 指标。您可以指定指标命名空间、名称、值、单位和时间戳。

more info (2)

使用 AWS IoT 指标操作创建 CloudWatch 规则时,您必须指定以下信息:

roleArn

允许访问 IAM 指标的 CloudWatch 角色。

metricNamespace

CloudWatch 指标命名空间名称。

metricName

CloudWatch 指标名称。

metricValue

CloudWatch 指标值。

metricUnit

CloudWatch 支持的指标单位。

metricTimestamp

可选 Unix 时间戳。

注意

确保与规则关联的角色拥有授予 cloudwatch:PutMetricData 权限的策略。

下面的 JSON 示例介绍了如何在 CloudWatch 规则中定义 AWS IoT 指标操作:

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

有关更多信息,请参阅 CloudWatch 指标

DynamoDB 操作

DynamoDB Actionmore info (3)
DynamoDB Action

通过 dynamoDB 操作,您可以将所有或部分 MQTT 消息写入 DynamoDB 表。

more info (3)

创建 DynamoDB 规则时,您必须指定以下信息:

hashKeyType

哈希键(也称为分区键)的数据类型。有效值为:"STRING""NUMBER"

hashKeyField

哈希键(也称为分区键)的名称。

hashKeyValue

哈希键的值。

rangeKeyType

可选。范围键(也称为排序键)的数据类型。有效值为:"STRING""NUMBER"

rangeKeyField

可选。范围键(也称为排序键)的名称。

rangeKeyValue

可选。范围键的值。

operation

可选。要执行的操作类型。该信息遵循替换模板,因此可以是 ${operation},但替换必须产生以下操作之一:INSERTUPDATEDELETE

payloadField

可选。负载将写入的字段的名称。如果省略此值,负载将写入 payload 字段。

table

DynamoDB 表的名称。

roleARN

允许访问 DynamoDB 表的 IAM 角色。该角色至少须允许 dynamoDB:PutItem IAM 操作。

写入 DynamoDB 表的数据是规则的 SQL 语句的结果。hashKeyValuerangeKeyValue 字段通常由表达式 (例如,“${topic()}”或“${timestamp()}”) 组成。

注意

非 JSON 数据以二进制数据形式写入 DynamoDB。DynamoDB 控制台以 Base64 编码文本格式显示数据。

确保与规则关联的角色拥有授予 dynamodb:PutItem 权限的策略。

下面的 JSON 示例介绍了如何在 dynamoDB 规则中定义 AWS IoT 操作:

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

有关更多信息,请参阅 Amazon DynamoDB 入门指南

DynamoDBv2 操作

DynamoDBv2 Actionmore info (4)
DynamoDBv2 Action

通过 dynamoDBv2 操作,您可以将所有或部分 MQTT 消息写入 DynamoDB 表。负载中的每个属性将写入 DynamoDB 数据库中的单独一列。

more info (4)

创建 DynamoDB 规则时,您必须指定以下信息:

roleARN

允许访问 DynamoDB 表的 IAM 角色。该角色至少须允许 dynamoDB:PutItem IAM 操作。

tableName

DynamoDB 表的名称。

注意

如果要定义 MQTT 消息负载,则它必须包含一个与表的主分区键相匹配的根级键,以及一个与表的主排序键相匹配的根级键。

写入 DynamoDB 表的数据是规则的 SQL 语句的结果。

注意

确保与规则关联的角色拥有授予 dynamodb:PutItem 权限的策略。

下面的 JSON 示例介绍了如何在 dynamoDB 规则中定义 AWS IoT 操作:

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

有关更多信息,请参阅 Amazon DynamoDB 入门指南

Amazon ES 操作

Amazon ES Actionmore info (5)
Amazon ES Action

通过 elasticsearch 操作,您可以将 MQTT 消息中的数据写入 Amazon Elasticsearch Service 域。然后,您可以使用 Kibana 等工具来查询和可视化 Amazon ES 中的数据。

more info (5)

使用 AWS IoT 操作创建 elasticsearch 规则时,您必须指定以下信息:

endpoint

您的 Amazon ES 域的终端节点。

index

您要在其中存储数据的 Amazon ES 索引。

type

您存储的文档类型。

id

每个文档的唯一标识符。

注意

确保与规则关联的角色拥有授予 es:ESHttpPut 权限的策略。

下面的 JSON 示例介绍了如何在 elasticsearch 规则中定义 AWS IoT 操作:

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

有关更多信息,请参阅《Amazon ES 开发人员指南》。

Firehose 操作

Firehose Actionmore info (6)
Firehose Action

firehose 操作可以将触发规则的 MQTT 消息中的数据发送至 Kinesis Data Firehose 流。

more info (6)

使用 firehose 操作创建规则时,您必须指定以下信息:

deliveryStreamName

消息数据写入的 Kinesis Data Firehose 流。

roleArn

允许访问 IAM 的 Kinesis Data Firehose 角色。

separator

将用于分隔写入 Firehose 流的记录的字符分隔符。有效值为:'\n'(换行符)、'\t'(制表符)、'\r\n'(Windows 换行符)、','(逗号)。

注意

确保与规则关联的角色拥有授予 firehose:PutRecord 权限的策略。

下面的 JSON 示例介绍了如何使用 AWS IoT 操作创建 firehose 规则:

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

有关更多信息,请参阅《Kinesis Data Firehose 开发人员指南》。

IoT Analytics 操作

IoT Analytics Actionmore info (7)
IoT Analytics Action

iotAnalytics 操作可将触发规则的 MQTT 消息中的数据发送至 AWS IoT Analytics 通道。

more info (7)

使用 iotAnalytics 操作创建规则时,您必须指定以下信息:

channelName

数据写入的 AWS IoT Analytics 通道的名称。

roleArn

允许访问 IAM 通道的 AWS IoT Analytics 角色。

附加到您指定的角色的策略应如下所示:

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

并具有如下所示的信任关系:

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

下面的 JSON 示例介绍了如何使用 AWS IoT 操作创建 iotAnalytics 规则:

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

有关更多信息,请参阅《AWS IoT Analytics 用户指南》。

Kinesis 操作

Kinesis Actionmore info (8)
Kinesis Action

通过 kinesis 操作,您可以将 MQTT 消息中的数据写入 Kinesis 流。

more info (8)

使用 AWS IoT 操作创建 kinesis 规则时,您必须指定以下信息:

stream

数据写入的 Kinesis 流。

partitionKey

用于确定将数据写入哪个分区的分区键。分区键通常由表达式 (例如,“${topic()}”或“${timestamp()}”) 组成。

注意

确保与规则关联的策略拥有 kinesis:PutRecord 权限。

下面的 JSON 示例介绍了如何在 kinesis 规则中定义 AWS IoT 操作:

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

有关更多信息,请参阅《Kinesis 开发人员指南》。

Lambda 操作

Lambda Actionmore info (9)
Lambda Action

lambda 操作会调用 Lambda 函数,并传入触发规则的 MQTT 消息。

more info (9)

要让 AWS IoT 调用 Lambda 函数,您必须配置一个策略,以便将 lambda:InvokeFunction 权限授予 AWS IoT。Lambda 函数使用基于资源的策略,因此您必须将该策略附加至 Lambda 函数本身。使用以下 CLI 命令附加授予 lambda:InvokeFunction 权限的策略:

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"

add-permission 命令的参数如下:

--function-name

您正在通过添加新权限来更新其资源策略的 Lambda 函数的名称。

--region

您的账户所处的 AWS 区域。

--principal

获取权限的委托人。这应该是 iot.amazonaws.com,以便授予 AWS IoT 调用 Lambda 函数的权限。

--source-arn

规则的 ARN。您可以使用 get-topic-rule CLI 命令来获取规则的 ARN。

--source-account

定义规则的 AWS 账户。

--statement-id

唯一的语句标识符。

--action

要在此语句中允许的 Lambda 操作。在本示例中,我们要允许 AWS IoT 调用 Lambda 函数,因此我们指定 lambda:InvokeFunction

注意

如果您在不提供源 ARN 的情况下为 AWS IoT 委托人添加权限,则通过 Lambda 操作创建规则的所有 AWS 账户都可以触发规则,以便从 Lambda 调用 AWS IoT 函数。

有关更多信息,请参阅 Lambda 权限模型

使用 lambda 操作创建规则时,您必须指定在触发规则后要调用的 Lambda 函数。

下面的 JSON 示例介绍了调用 Lambda 函数的规则:

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

有关更多信息,请参阅《AWS Lambda 开发人员指南》。

Republish 操作

Republish Actionmore info (10)
Republish Action

republish 操作允许您将触发角色的消息重新发布至另一个 MQTT 主题。

more info (10)

使用 republish 操作创建规则时,您必须指定以下信息:

topic

消息重新发布到的 MQTT 主题。

roleArn

允许发布至 MQTT 主题的 IAM 角色。

注意

确保与规则关联的角色拥有授予 iot:Publish 权限的策略。

{ "rule": { "sql": "SELECT * FROM 'some/topic'", "ruleDisabled": false, "actions": [{ "republish": { "topic": "another/topic", "roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish" } }] } }

S3 操作

S3 Actionmore info (11)
S3 Action

s3 操作可以将触发规则的 MQTT 消息中的数据写入 Amazon S3 存储桶。

more info (11)

使用 AWS IoT 操作创建 s3 规则时,您必须指定以下信息(可选项 cannedacl 除外):

bucket

数据写入的 Amazon S3 存储桶。

cannedacl

Amazon S3 标准 ACL,用于控制对由对象键标识的对象的访问。有关更多信息,请参阅 S3 标准 ACL(列出了允许的值)。请注意,cannedacl 是可选项。

key

数据写入的文件路径。例如,如果此参数的值为“${topic()}/${timestamp()}”,消息发送到的主题为“this/is/my/topic,”,当前时间戳为 1460685389,则数据将写入 Amazon S3 上“this/is/my/topic”文件夹中名为“1460685389”的文件。

注意

使用静态键将导致每次调用规则都会覆盖 Amazon S3 中的单个文件。更常见的使用案例是使用消息时间戳或其他唯一的消息标识符,这样可以在 Amazon S3 中针对接收的每个消息保存一个新文件。

roleArn

允许访问 IAM 存储桶的 Amazon S3 角色。

注意

确保与规则关联的角色拥有授予 s3:PutObject 权限的策略。

下面的 JSON 示例介绍了如何在 s3 规则中定义 AWS IoT 操作:

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

有关更多信息,请参阅《Amazon S3 开发人员指南》。

Salesforce 操作

Salesforce Actionmore info (12)
Salesforce Action

salesforce 操作将来自触发了规则的 MQTT 消息的数据发送到 Salesforce IoT 输入流。

more info (12)

使用 salesforce 操作创建规则时,您必须指定以下信息:

url

由 Salesforce IoT 输入流公开的 URL。在创建输入流时,可从 Salesforce IoT 平台获得该 URL。请参阅 Salesforce IoT 文档以了解更多信息。

token

用于验证对指定的 Salesforce IoT 输入流的访问的令牌。在创建输入流时,可从 Salesforce IoT 平台获得该令牌。请参阅 Salesforce IoT 文档以了解更多信息。

注意

这些参数不支持替换。

下面的 JSON 示例介绍了如何使用 AWS IoT 操作创建 salesforce 规则:

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

有关更多信息,请参阅 Salesforce IoT 文档。

SNS 操作

SNS Actionmore info (13)
SNS Action

sns 操作可将触发规则的 MQTT 消息中的数据作为 SNS 推送通知发送。

more info (13)

使用 sns 操作创建规则时,您必须指定以下信息:

messageFormat

消息格式。接受的值为“JSON”和“RAW”。 该属性的默认值为“RAW”。 SNS 使用此设置来确定是否应解析负载,以及是否应提取负载的特定于平台的相关部分。

roleArn

允许访问 SNS 的 IAM 角色。

targetArn

推送通知将发送到的 SNS 主题或单个设备。

注意

确保与规则关联的策略拥有 sns:Publish 权限。

下面的 JSON 示例介绍了如何在 sns 规则中定义 AWS IoT 操作:

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

有关更多信息,请参阅《Amazon SNS 开发人员指南》。

SQS 操作

SQS Actionmore info (14)
SQS Action

sqs 操作可将触发规则的 MQTT 消息中的数据发送至 SQS 队列。

more info (14)

使用 sqs 操作创建规则时,您必须指定以下信息:

queueUrl

数据写入的 SQS 队列的 URL。

useBase64

如果您希望 MQTT 消息数据在写入 SQS 队列前进行 Base64 编码,则设置为 true。否则,设置为 false

roleArn

允许访问 SQS 队列的 IAM 角色。

注意

确保与规则关联的角色拥有授予 sqs:SendMessage 权限的策略。

下面的 JSON 示例介绍了如何使用 AWS IoT 操作创建 sqs 规则:

{ "rule": { "sql": "SELECT * FROM 'some/topic'", "ruleDisabled": false, "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 } }] } }

有关更多信息,请参阅《Amazon SQS 开发人员指南》。

Step Functions 操作

Step Functions Actionmore info (15)
Step Functions Action

执行 stepFunctions 操作可以开始执行 Step Functions 状态机。

more info (15)

使用 stepFunctions 操作创建规则时,您必须指定以下信息:

executionNamePrefix

(可选)将为状态机执行操作指定名称,由此前缀后加 UUID 组成。如果未提供名称,Step Functions 会自动为每次状态机执行操作创建一个唯一的名称。

stateMachineName

将开始执行的 Step Functions 状态机名称。

roleArn

授予 IoT 权限以开始执行状态机(“Action”:“states:StartExecution”)的角色的 ARN。

以下示例显示了一个应附加到角色的策略:

{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": "states:StartExecution", "Resource": [ * ] } }

下面的 JSON 示例介绍了如何使用 AWS IoT 操作创建 stepFunctions 规则:

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

有关更多信息,请参阅《Step Functions 开发人员指南》。