AWS IoT 规则操作 - AWS IoT
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

AWS IoT 规则操作

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

  • cloudwatchAlarm – 更改 CloudWatch 警报。

  • cloudwatchLogs 将数据发送给 CloudWatch Logs。

  • cloudwatchMetric – 捕获 CloudWatch 指标。

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

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

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

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

  • http – 将数据发布到 HTTPS 终端节点。

  • iotSiteWise - 将数据发送到 AWS IoT SiteWise 中的资源属性。

  • kinesis – 将数据写入 Kinesis 流。

  • lambda – 调用 Lambda 函数。

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

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

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

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

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

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

注意

AWS IoT 规则引擎可多次尝试执行一个操作,以防出现间歇性错误。如果所有尝试都失败,将丢弃消息,并且 CloudWatch 日志中将记录此错误。您可以为在发生故障后调用的每条规则指定一个错误操作。有关更多信息,请参阅错误处理(错误操作)

某些规则操作会触发与 AWS Key Management Service (AWS KMS) 集成的服务中的操作,以支持静态数据加密。如果您使用客户托管的 AWS KMS 客户主密钥 (CMK) 对数据进行静态加密,则服务必须具有代表调用方使用 CMK 的权限。请参阅相应服务指南中的数据加密主题,以了解如何管理客户托管 CMK 的权限。有关 CMK 和客户托管 CMK 的更多信息,请参阅 AWS Key Management Service Developer Guide 中的 AWS Key Management Service 概念

每个操作均有详细介绍。

CloudWatch 警报操作

CloudWatch alarm action

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

More information (1)

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

roleArn

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

alarmName

CloudWatch 警报名称。

stateReason

警报更改的原因。

stateValue

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

注意

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

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

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

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

Substitution Templates

CloudWatch 警报操作支持 CLI 和控制台的 alarmNamestateValuestateReason 参数中的替换模板。但是,alarmName 参数只能在 CLI 中替换。有关替换模板的更多信息,请参阅替换模板

以下是 CLI 中 CloudWatch 警报操作的替换模板示例。

aws iot get-topic-rule --rule-name "CWAlarmSubsitutionExample" { "ruleArn": "arn:aws:iot:us-east-1:418092313572:rule/CWAlarmSubsitutionExample", "rule": { "awsIotSqlVersion": "2016-03-23", "sql": "SELECT topic() AS topic FROM 'cwalarmsubstopic'", "ruleDisabled": false, "actions": [ { "cloudwatchAlarm": { "stateReason": "${topic()}", "roleArn": "arn:aws:iam::418092313572:role/service-role/ArunavTest", "alarmName": "$($newuuid())", "stateValue": "$($newuuid())" } } ], "ruleName": "CWAlarmSubsitutionExample" } }

CloudWatch Logs 操作

CloudWatch Logs action

CloudWatch 日志操作允许您将数据发送到 CloudWatch Logs。您可以指定操作要向其发送数据的 CloudWatch 日志组。

More information (2)

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

roleArn

允许访问 CloudWatch 日志的 IAM 角色。

logGroupName

操作向其发送数据的 CloudWatch 日志组。

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

{ "topicRulePayload": { "sql": "SELECT * FROM 'some/topic'", "ruleDisabled": false, "awsIotSqlVersion": "2016-03-23", "actions": [{ "cloudwatchLogs": { "roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw", "logGroupName": "IotLogs" } }] } }

有关更多信息,请参阅 CloudWatch Logs 入门。如果您使用客户托管的 AWS KMS CMK 对 CloudWatch Logs 中的日志数据进行加密,则服务必须具有代表调用方使用 CMK 的权限。有关更多信息,请参阅 Amazon CloudWatch Logs 用户指南 中的使用 AWS KMS 加密 CloudWatch Logs 中的日志数据

CloudWatch 指标操作

CloudWatch metric action

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

More information (3)

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

roleArn

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

metricNamespace

CloudWatch 指标命名空间名称。

metricName

CloudWatch 指标名称。

metricValue

CloudWatch 指标值。

metricUnit

CloudWatch 支持的指标单位。

metricTimestamp

可选 Unix 时间戳。

注意

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

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

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

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

Substitution Templates

CloudWatch 指标操作支持 CLI 和控制台的 metricUnitmetricTimestampmetricNamespacemetricValuemetricName 参数中的替换模板。有关替换模板的更多信息,请参阅替换模板

以下是 CLI 中 CloudWatch 指标操作的替换模板示例。

aws iot get-topic-rule --rule-name "CWMetricSubstitutionExample" { "ruleArn": "arn:aws:iot:us-east-1:418092313572:rule/CWMetricSubstitutionExample", "rule": { "awsIotSqlVersion": "2016-03-23", "sql": "SELECT topic() AS topic FROM 'cwmetricsubstemplate'", "ruleDisabled": false, "actions": [ { "cloudwatchMetric": { "metricUnit": "${topic()}", "roleArn": "arn:aws:iam::418092313572:role/service-role/ArunavTest", "metricTimestamp": "${newuuid()}", "metricNamespace": "${topic()}", "metricValue": "${newuuid()}", "metricName": "${topic()}" } } ], "ruleName": "CWMetricSubstitutionExample" } }

DynamoDB 操作

DynamoDB action

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

More information (4)

创建 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 示例介绍了如何在 AWS IoT 规则中定义 dynamoDB 操作:

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

有关更多信息,请参见 Amazon DynamoDB 入门指南。如果您使用客户托管的 AWS KMS CMK 对 DynamoDB 中的数据进行静态加密,则服务必须具有代表调用方使用 CMK 的权限。有关更多信息,请参阅 Amazon DynamoDB 入门指南 中的客户托管 CMK

Substitution Templates

dynamoDB 操作支持 CLI 和控制台的 tableNamehasKeyFieldhashKeyValuepayloadFieldhashKeyTyperangeKeyFieldrangeKeyValuerangeKeyType 参数中的替换模板。但是,tableNamehasKeyFieldhashKeyTyperangeKeyType 参数只能在 CLI 中替换。有关替换模板的更多信息,请参阅替换模板

以下是 CLI 中 dynamoDB 操作的替换模板示例。

aws iot get-topic-rule --rule-name "DynamoV1SubstitutionExample" { "ruleArn": "arn:aws:iot:us-east-1:418092313572:rule/DynamoV1SubstitutionExample", "rule": { "awsIotSqlVersion": "2016-03-23", "sql": "SELECT topic() AS topic FROM 'ddbv1substopic'", "ruleDisabled": false, "actions": [ { "dynamoDB": { "rangeKeyType": "${topic()}", "payloadField": "${topic()}", "hashKeyType": "${topic()}", "hashKeyField": "hashKeyField", "roleArn": "arn:aws:iam::418092313572:role/service-role/ArunavTest", "tableName": ""${topic()}"", "hashKeyValue": "${topic()}", "rangeKeyValue": "${topic()}", "rangeKeyField": "${topic()}" } } ], "ruleName": "DynamoV1SubstitutionExample" } }

DynamoDBv2 操作

DynamoDBv2 action

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

More information (5)

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

roleARN

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

tableName

DynamoDB 表的名称。

注意

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

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

注意

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

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

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

有关更多信息,请参见 Amazon DynamoDB 入门指南。如果您使用客户托管的 AWS KMS CMK 对 DynamoDB 中的数据进行静态加密,则服务必须具有代表调用方使用 CMK 的权限。有关更多信息,请参阅 Amazon DynamoDB 入门指南 中的客户托管 CMK

Substitution Templates

dynamoDBv2 操作支持 CLI 中 tableName 参数的替换模板。有关替换模板的更多信息,请参阅替换模板

以下是 CLI 中 dynamoDBv2 操作的替换模板示例。

aws iot get-topic-rule --rule-name "DDBV2SubsExample" { "ruleArn": "arn:aws:iot:us-east-1:418092313572:rule/DDBV2SubsExample", "rule": { "awsIotSqlVersion": "2015-10-08", "sql": "SELECT topic() AS topic FROM 'ddbvssubstopic'", "ruleDisabled": false, "actions": [ { "dynamoDBv2": { "putItem": { "tableName": "${topic()}" }, "roleArn": "arn:aws:iam::418092313572:role/service-role/ArunavTest" } } ], "ruleName": "DDBV2SubsExample" } }

Elasticsearch 操作

Elasticsearch action

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

More information (6)

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

endpoint

您的 Amazon Elasticsearch Service 域的终端节点。

index

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

type

您存储的文档类型。

id

每个文档的唯一标识符。

注意

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

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

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

有关更多信息,请参见 Amazon Elasticsearch Service 开发人员指南。如果您使用客户托管的 AWS KMS CMK 对 Elasticsearch 中的数据进行静态加密,则服务必须具有代表调用方使用 CMK 的权限。有关更多信息,请参阅 Amazon Elasticsearch Service 开发人员指南 中的 Amazon Elasticsearch Service 的数据静态加密

Substitution Templates

elasticsearch 操作支持 CLI 的 endpoint 参数中的替换模板,以及 CLI 和控制台的 typeindex 参数中的替换模板。有关替换模板的更多信息,请参阅替换模板

以下是 CLI 中 elasticsearch 操作的替换模板示例。

aws iot get-topic-rule --rule-name "ESWithAllSubs" { "ruleArn": "arn:aws:iot:us-east-1:418092313572:rule/ElasticSearchSubstitutionExample", "rule": { "awsIotSqlVersion": "2016-03-23", "sql": "SELECT topic() AS topic FROM 'subsestopic'", "ruleDisabled": false, "actions": [ { "elasticsearch": { "index": "${topic()}", "roleArn": "arn:aws:iam::418092313572:role/service-role/ArunavTest", "endpoint": "https:~/~/search-arunavtestdoman-vaina2nrodxolq5ojs3c2psj4q.us-east-1.es.amazonaws.com", "type": "${topic()}", "id": "SomeID" } } ], "ruleName": "ElasticSearchSubstitutionExample" } }

Firehose 操作

Firehose action

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

More information (7)

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

deliveryStreamName

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

roleArn

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

分隔符

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

注意

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

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

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

有关更多信息,请参见 Amazon Kinesis Data Firehose 开发人员指南。如果您使用 Kinesis Data Firehose 将数据发送到 Amazon S3 存储桶,并且您使用客户托管的 AWS KMS CMK 对 Amazon S3 中的数据进行静态加密,则 Kinesis Data Firehose 必须具有对存储桶的访问权限,并且有权代表调用方使用 CMK。有关更多信息,请参阅 Amazon Kinesis Data Firehose 开发人员指南 中的向 Kinesis Data Firehose 授予对 Amazon S3 目标的访问权限

Substitution Templates

firehose 操作支持 CLI 中 deliveryStreamName 参数的替换模板。有关替换模板的更多信息,请参阅替换模板

以下是 CLI 中 firehose 操作的替换模板示例。

aws iot get-topic-rule --rule-name "FirehoseSubstitutionExample" { "ruleArn": "arn:aws:iot:us-east-1:418092313572:rule/FirehoseSubstitutionExample", "rule": { "awsIotSqlVersion": "2016-03-23", "sql": "SELECT topic() as topic FROM 'firehosesubstopic'", "ruleDisabled": false, "actions": [ { "firehose": { "roleArn": "arn:aws:iam::418092313572:role/service-role/ArunavTest", "deliveryStreamName": "${topic()}" } } ], "ruleName": "FirehoseSubstitutionExample" } }

HTTP 操作

HTTP action

http 操作将数据从触发规则的 MQTT 消息发送到 Web 应用程序或服务以供进一步处理,而无需编写任何代码。您将数据发送到的终端节点必须先经过验证,然后规则引擎才能使用它。

More information (8)

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

url

通过 HTTP POST 发送消息的 HTTPS URL。您可以在 URL 中使用替换模板。

confirmationUrl

可选。如果指定,AWS IoT 使用确认 URL 创建匹配的主题规则目标。您必须先启用主题规则目标,然后才能在 http 操作中它。有关更多信息,请参阅 使用主题规则目标。如果您使用替换模板,则必须先手动创建主题规则目标,然后才能使用 http 操作。confirmationUrl 必须是 url 的前缀。

urlconfirmationUrl 之间的关系由以下内容描述:

  • 如果 url 为硬编码且未提供 confirmationUrl,则我们隐式地将 url 字段视为 confirmationUrl。AWS IoT 为 url 创建主题规则目标。

  • 如果 urlconfirmationUrl 为硬编码,则 url 必须以 confirmationUrl 开头。AWS IoT 为 confirmationUrl 创建主题规则目标。

  • 如果 url 包含替换模板,则必须指定 confirmationUrl 并且 url 必须以 confirmationUrl 开头。如果 confirmationUrl 包含替换模板,则必须先手动创建主题规则目标,然后才能使用 http 操作。如果 confirmationUrl 不包含替换模板,则 AWS IoT 为 confirmationUrl 创建主题规则目标。

headers

可选。您要包含在 HTTP 请求中的任意标头。

key

标头的键。不支持替换模板。

value

标头的值。支持替换模板。

auth

可选。规则引擎在连接到 url 参数中指定的终端节点 URL 时使用的身份验证。目前,签名版本 4 是唯一支持的身份验证类型。有关更多信息,请参阅 HTTP 授权

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

{ "topicRulePayload": { "sql": "select * from 'a/b'", "awsIotSqlVersion": "2016-03-23", "ruleDisabled": false, "actions": [{ "http": { "url": "https://www.example.com/subpath", "confirmationUrl": "https://www.example.com", "headers": [{ "key": "static_header_key", "value": "static_header_value" }, { "key": "substitutable_header_key", "value": "${value_from_payload}" }] } }] } }

当负载为 JSON 格式时,默认内容类型是 application/json。否则,它是 application/octet-stream。您可以在标头中,使用键内容类型(不区分大小写)指定确切的内容类型来覆盖它。

HTTP action retry logic

AWS IoT 规则引擎根据以下规则重试 http 操作:

  • 规则引擎尝试至少发送一次消息。

  • 规则引擎最多重试两次。最大尝试次数为三次。

  • 在下列情况中,规则引擎不会尝试重试:

    • 之前的尝试提供了大于 16384 字节的响应。

    • 下游 Web 服务或应用程序在尝试之后关闭了 TCP 连接。

    • 完成包括尝试在内的请求总用时超过了请求超时限制。

    • 该请求返回除 429、500-599 之外的 HTTP 状态代码。

注意

标准数据传输费用适用于重试操作。

Kinesis 操作

Kinesis action

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

More information (12)

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

stream

数据写入的 Kinesis 流。

partitionKey

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

注意

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

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

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

有关更多信息,请参见 Amazon Kinesis Data Streams 开发人员指南。如果您使用客户托管的 AWS KMS CMK 对 Kinesis Data Streams 中的数据进行静态加密,则服务必须具有代表调用方使用 CMK 的权限。有关更多信息,请参阅 Amazon Kinesis Data Streams 开发人员指南 中的使用用户生成的 KMS 主密钥的权限

Substitution Templates

kinesis 操作支持 CLI 的 streamName 参数中的替换模板,以及 CLI 和控制台的 partitionKey 参数中的替换模板。有关替换模板的更多信息,请参阅替换模板

以下是 CLI 中 kinesis 操作的替换模板示例。

aws iot get-topic-rule --rule-name "KinesisSubstitutionExample" { "ruleArn": "arn:aws:iot:us-east-1:418092313572:rule/KinesisSubstitutionExample", "rule": { "description": "", "ruleName": "KinesisSubstitutionExample", "actions": [ { "kinesis": { "roleArn": "arn:aws:iam::418092313572:role/service-role/ArunavTest", "streamName": "${topic()}" "partitionKey": "${newuuid()}" } } ], "sql": "SELECT topic() as topic FROM 'kinesissubstopic'", "awsIotSqlVersion": "2016-03-23", "ruleDisabled": false } }

Lambda 操作

Lambda action

lambda 操作会调用 Lambda 函数,并传入触发规则的 MQTT 消息。Lambda 函数以异步方式运行。

More information (13)

Lambda 函数以异步方式执行。

为了让 AWS IoT 调用 Lambda 函数,您必须配置一个策略以向 AWS IoT 授予 lambda:InvokeFunction 权限。您只能调用在 Lambda 策略所在区域中定义的 Lambda 函数。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 账户都可以触发规则,以便从 AWS IoT 调用 Lambda 函数。

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

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

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

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

如果您未指定 Lambda 函数的版本或别名,则将执行该函数的最新版本。如果要执行 Lambda 函数的特定版本,则可执行其版本或别名。要指定一个版本或别名,请将该版本或别名附加到 Lambda 函数的 ARN。例如:

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

有关版本控制和别名的更多信息,请参阅 AWS Lambda 函数版本控制和别名。有关 AWS Lambda 的更多信息,请参阅 AWS Lambda Developer Guide

如果您使用客户托管的 AWS KMS CMK 对 AWS Lambda 中的数据进行静态加密,则服务必须具有代表调用方使用 CMK 的权限。有关更多信息,请参阅 AWS Lambda 开发人员指南 中的静态加密

Substitution Templates

lambda 操作支持 CLI 中 functionArn 参数的替换模板。有关替换模板的更多信息,请参阅替换模板

以下是 CLI 中 lambda 操作的替换模板示例。

aws iot get-topic-rule --rule-name "LambdaSubstitutionExample" { "ruleArn": "arn:aws:iot:us-east-1:418092313572:rule/LambdaSubstitutionExample", "rule": { "awsIotSqlVersion": "2016-03-23", "sql": "SELECT topic() AS topic FROM 'lamdbasubsexample'", "ruleDisabled": false, "actions": [ { "lambda": { "functionArn": "arn:aws:lambda:us-east-1:418092313572:${topic()}" } } ], "ruleName": "LambdaSubstitutionExample" } }

Republish 操作

Republish action

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

More information (14)

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

topic

消息重新发布到的 MQTT 主题。如果您要重新发布到以 $ 开头的保留主题,请改为使用 $$。例如,如果您正在重新发布到设备影子主题(例如 $$aws/things/MyThing/shadow/update),请使用 $$aws/things/MyThing/shadow/update 格式指定主题。

roleArn

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

qos

可选。重新发布消息时要使用的服务质量 (QoS) 级别。有效值为 01。默认值为 0

注意

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

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

republish 操作支持控制台和 CLI 的 topic 参数中的替换模板。有关替换模板的更多信息,请参阅替换模板

以下是 CLI 中 republish 操作的替换模板示例。

aws iot get-topic-rule --rule-name "RepublishSubstitutionExample" { "ruleArn": "arn:aws:iot:us-east-1:418092313572:rule/RepublishSubstitutionExample", "rule": { "awsIotSqlVersion": "2016-03-23", "sql": "SELECT *, topic() AS topic FROM 'my/iot/topic'", "ruleDisabled": false, "actions": [ { "republish": { "topic": "${topic()}/republish", "roleArn": "arn:aws:iam::418092313572:role/service-role/ArunavTest" } } ], "ruleName": "RepublishSubstitutionExample" } }

S3 操作

S3 action

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

More information (15)

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

bucket

数据写入的 Amazon S3 存储桶。

cannedacl

可选。Amazon S3 标准 ACL,用于控制对由对象键标识的对象的访问。有关更多信息,包括允许的值,请参阅 S3 标准 ACL

key

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

注意

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

roleArn

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

注意

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

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

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

有关更多信息,请参见 Amazon Simple Storage Service 开发人员指南。如果您使用客户托管的 AWS KMS CMK 对 Amazon S3 中的数据进行静态加密,则服务必须具有代表调用方使用 CMK 的权限。有关更多信息,请参阅 Amazon Simple Storage Service 开发人员指南 中的 AWS 托管 CMK 和客户托管 CMK

Substitution Templates

s3 操作支持 CLI 中 bucketName 参数以及控制台中 key 参数的替换模板。有关替换模板的更多信息,请参阅替换模板

以下是 CLI 中 S3 操作的替换模板示例。

aws iot get-topic-rule --rule-name "S3WithAllSubs" { "ruleArn": "arn:aws:iot:us-east-1:418092313572:rule/S3SubstitutionTemplateExample", "rule": { "awsIotSqlVersion": "2016-03-23", "sql": "SELECT topic() as topic FROM 's3substopic'", "ruleDisabled": false, "actions": [ { "s3": { "roleArn": "arn:aws:iam::418092313572:role/service-role/S3TestRole", "bucketName": "s3substopic", "key": "${newuuid()}" } } ], "ruleName": "S3SubstitutionTemplateExample" } }

Salesforce 操作

Salesforce action

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

More information (16)

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

url

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

token

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

注意

这些参数不支持替换。

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

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

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

SNS 操作

SNS action

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

More information (17)

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

messageFormat

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

roleArn

允许访问 SNS 的 IAM 角色。

targetArn

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

注意

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

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

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

有关更多信息,请参见 Amazon Simple Notification Service 开发人员指南。如果您使用客户托管的 AWS KMS CMK 对 Amazon SNS 中的数据进行静态加密,则服务必须具有代表调用方使用 CMK 的权限。有关更多信息,请参阅 Amazon Simple Notification Service 开发人员指南 中的密钥管理

Substitution Templates

sns 操作支持 CLI 中 targetArn 参数的替换模板。有关替换模板的更多信息,请参阅替换模板

以下是 CLI 中 sns 操作的替换模板示例。

aws iot get-topic-rule --rule-name "SNSSubstitutionExample" { "ruleArn":"arn:aws:iot:us-east-1:418092313572:rule/SNSSubstitutionExample", "rule":{ "awsIotSqlVersion":"2016-03-23", "sql":"SELECT topic() as topic FROM 'snssubstopic'", "ruleDisabled":false, "actions":[ { "sns":{ "targetArn":"arn:aws:sns:us-east-1:418092313572:${topic()}", "roleArn":"arn:aws:iam::418092313572:role/service-role/SNSTestRole", "messageFormat":"RAW" } } ], "ruleName":"SNSSubstitutionExample" } }

SQS 操作

SQS action

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

More information (18)

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

queueUrl

数据写入的 SQS 队列的 URL。

useBase64

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

roleArn

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

注意

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

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

{ "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 操作不支持 SQS FIFO 队列。由于规则引擎是一个完全分布式服务,因此无法保证触发 SQS 操作时的消息顺序。

有关更多信息,请参见 Amazon Simple Queue Service 开发人员指南。如果您使用客户托管的 AWS KMS CMK 对 Amazon SQS 中的数据进行静态加密,则服务必须具有代表调用方使用 CMK 的权限。有关更多信息,请参阅 Amazon Simple Queue Service 开发人员指南 中的密钥管理

Substitution Templates

sqs 操作支持 CLI 中 queueUrl 参数的替换模板。有关替换模板的更多信息,请参阅替换模板

以下是 CLI 中 sqs 操作的替换模板示例。

aws iot get-topic-rule --rule-name "SQSSubstitutionExample" { "ruleArn": "arn:aws:iot:us-east-1:418092313572:rule/SQSSubstitutionExample", "rule": { "awsIotSqlVersion": "2016-03-23", "sql": "SELECT topic() AS topic FROM 'sqssubstopic'", "ruleDisabled": false, "actions": [ { "sqs": { "queueUrl": "https:~/~/sqs.us-east-1.amazonaws.com/418092313572/${topic()}", "roleArn": "arn:aws:iam::418092313572:role/service-role/ArunavTest" } } ], "ruleName": "SQSSubstitutionExample" } }

Step Functions 操作

Step Functions action

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

More information (19)

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

executionNamePrefix

可选。为状态机名称执行提供的名称由此前缀后跟一个 UUID 组成。Step Functions 为每个状态机执行创建一个唯一的名称(如果未提供)。

stateMachineName

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

roleArn

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

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

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

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

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

有关更多信息,请参见 AWS Step Functions 开发人员指南