本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 的规则 Amazon IoT
Rules
规则使您的设备能够与之交互 Amazon Web Services 服务。基于 MQTT 主题流分析规则并执行操作。您可以使用规则来支持以下任务：
+ 补充或筛选从设备接收的数据。
+ 将从设备接收的数据写入 Amazon DynamoDB 数据库。
+ 将文件保存到 Amazon S3。
+ 向使用 Amazon SNS 的所有用户发送推送通知。
+ 将数据发布到 Amazon SQS 队列。
+ 调用 Lambda 函数来提取数据。
+ 使用 Amazon Kinesis 处理来自大量设备的消息。
+ 向亚马逊 OpenSearch 服务发送数据。
+ 捕获 CloudWatch 指标。
+ 更改 CloudWatch 警报。
+ 将 MQTT 消息中的数据发送到 Amazon SageMaker AI，以便根据机器学习 (ML) 模型进行预测。
+ 向 Salesforce物联网输入流发送消息。
+ 开始 Step Functions 状态机的过程。
+ 向 Amazon IoT Events 输入发送消息数据。
+ 将消息数据发送到 Amazon IoT SiteWise中的资产属性。
+ 将消息数据发送到 Web 应用程序或服务。
您的规则可以使用通过支持的 publish/subscribe 协议的 MQTT 消息。[设备通信协议](protocols.md)您还可以使用 B [asic Ingest](iot-basic-ingest.md) 功能将设备数据安全地发送到之前 Amazon Web Services 服务 列出的设备，而不会产生[消息收发](https://www.amazonaws.cn/iot-core/pricing/)费用。B [asic Ingest](iot-basic-ingest.md) 功能通过从摄取路径中移除 publish/subscribe 消息代理来优化数据流。这使其具有成本效益，同时仍保留了的安全性和数据处理功能 Amazon IoT。
在执行这些操作之前 Amazon IoT ，您必须向其授予代表您访问 Amazon 资源的权限。执行操作时，您需要为所使用的操作支付标准费用。 Amazon Web Services 服务
**Topics**
+ [
# 授予 Amazon IoT 规则所需的访问权限
](iot-create-role.md)
+ [
# 传递角色权限
](pass-role.md)
+ [
# 创建 Amazon IoT 规则
](iot-create-rule.md)
+ [
# 管理 Amazon IoT 规则
](iot-managae-rule.md)
+ [
# Amazon IoT 规则动作
](iot-rule-actions.md)
+ [
## 排除规则问题
](#iot-troubleshoot-rule)
+ [
# 使用规则访问跨账户资源 Amazon IoT
](accessing-cross-account-resources-using-rules.md)
+ [
# 错误处理（错误操作）
](rule-error-handling.md)
+ [
# 借助基本摄取功能，降低消息收发成本
](iot-basic-ingest.md)
+ [
# Amazon IoT SQL 参考
](iot-sql-reference.md)
# 授予 Amazon IoT 规则所需的访问权限
授予 访问权限
使用 IAM 角色控制每条规则有权访问的 Amazon 资源。在创建规则之前，您必须使用允许访问所需 Amazon 资源的策略创建 IAM 角色。 Amazon IoT 在实施规则时扮演这个角色。
**完成以下步骤以创建 IAM 角色和 Amazon IoT 策略，以授予 Amazon IoT 规则所需的访问权限 (Amazon CLI)。**
1. 将以下信任策略文档（该文档授予代入该角色的 Amazon IoT 权限）保存到名为的文件中`iot-role-trust.json`。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:iot:us-east-1:123456789012:rule/rulename"
}
}
}
]
}
```
使用 [create-role](https://docs.amazonaws.cn/cli/latest/reference/iam/create-role.html) 命令，指定 `iot-role-trust.json` 文件，创建 IAM 角色：
```
aws iam create-role --role-name my-iot-role --assume-role-policy-document file://iot-role-trust.json
```
此命令的输出如下所示：
```
{
"Role": {
"AssumeRolePolicyDocument": "url-encoded-json",
"RoleId": "AKIAIOSFODNN7EXAMPLE",
"CreateDate": "2015-09-30T18:43:32.821Z",
"RoleName": "my-iot-role",
"Path": "/",
"Arn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}
```
1. 将以下 JSON 保存到名为 `my-iot-policy.json` 的文件中。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "dynamodb:*",
"Resource": "*"
}
]
}
```
此 JSON 是一个示例策略文档，用于向 Amazon IoT 管理员授予对 DynamoDB 的访问权限。
在担任角色后，使用 [create-](https://docs.amazonaws.cn/cli/latest/reference/iam/create-policy.html) p Amazon IoT olicy 命令授予对 Amazon 资源的访问权限，并传入`my-iot-policy.json`文件：
```
aws iam create-policy --policy-name my-iot-policy --policy-document file://my-iot-policy.json
```
有关如何在的策略 Amazon Web Services 服务 中授予访问权限的更多信息 Amazon IoT，请参阅[创建 Amazon IoT 规则](iot-create-rule.md)。
[create-policy](https://docs.amazonaws.cn/cli/latest/reference/iam/create-policy.html) 命令的输出中包含该策略的 ARN。将策略附加到角色。
```
{
"Policy": {
"PolicyName": "my-iot-policy",
"CreateDate": "2015-09-30T19:31:18.620Z",
"AttachmentCount": 0,
"IsAttachable": true,
"PolicyId": "ZXR6A36LTYANPAI7NJ5UV",
"DefaultVersionId": "v1",
"Path": "/",
"Arn": "arn:aws:iam::123456789012:policy/my-iot-policy",
"UpdateDate": "2015-09-30T19:31:18.620Z"
}
}
```
1. 使用[attach-role-policy](https://docs.amazonaws.cn/cli/latest/reference/iam/attach-role-policy.html)命令将您的策略附加到您的角色：
```
aws iam attach-role-policy --role-name my-iot-role --policy-arn "arn:aws:iam::123456789012:policy/my-iot-policy"
```
## 撤销规则引擎访问
要立即撤销规则引擎访问，请执行以下操作
1. 从[信任策略](https://docs.amazonaws.cn/iot/latest/developerguide/iot-create-role.html)中移除 iot.amazonaws.com
1. 按照步骤[撤销物联网角色会话](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_roles_use_revoke-sessions.html)
# 传递角色权限
传递角色权限
规则定义的一部分是 IAM 角色，该角色授予对规则操作中指定的资源的访问权限。当调用规则的操作时，规则引擎会代入该角色。角色的定义必须与规则 Amazon Web Services 账户 相同。
在创建或替换规则时，您实际上将角色提交到规则引擎中。无需 `iam:PassRole` 权限即可执行该操作。为验证您拥有该权限，您需要创建一个策略以便授予 `iam:PassRole` 权限，并将其附加到您的 IAM 用户。以下策略介绍了如何向角色提供 `iam:PassRole` 权限。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Stmt1",
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": [
"arn:aws:iam::123456789012:role/myRole"
]
}
]
}
```
在此策略示例中，将 `iam:PassRole` 权限授予了角色 `myRole`。该角色使用角色的 ARN 指定。将此策略附加到您的 IAM 用户或用户所属的角色。有关更多信息，请参阅[使用管理的策略](https://docs.amazonaws.cn/service-authorization/latest/reference/access_policies_managed-using.html)。
**注意**
Lambda 函数使用基于资源的策略，该策略直接附加至 Lambda 函数本身。在您创建调用 Lambda 函数的规则时，您未传递角色，因此创建规则的用户无需 `iam:PassRole` 权限。有关 Lambda 函数授权的更多信息，请参阅[使用资源策略授予权限](https://docs.amazonaws.cn/lambda/latest/dg/intro-permission-model.html#intro-permission-model-access-policy)。
# 创建 Amazon IoT 规则
创建规则
您可以创建 Amazon IoT 规则来路由来自互联事物的数据，以便与其他 Amazon 服务进行交互。 Amazon IoT 规则由以下部分组成：
**规则的组成部分**
| 组件 | 说明 | 必需/可选 |
| --- | --- | --- |
| 规则名称 | 规则的名称。注意，我们建议不要在您的规则名称中使用个人身份信息。 | 必需。 |
| 规则描述 | 规则的文字说明。注意，我们建议不要在您的规则描述中使用个人身份信息。 | 可选。 |
| SQL 语句 | 一种简化的 SQL 语法，用于筛选接收的 MQTT 主题相关消息并向其它推送数据。有关更多信息，请参阅 [Amazon IoT SQL 参考](iot-sql-reference.md)。 | 必需。 |
| SQL 版本 | 评估规则时使用的 SQL 规则引擎的版本。尽管该属性是可选的，但我们强烈建议您指定 SQL 版本。默认情况下， Amazon IoT Core 控制台将此属性设置`2016-03-23`为。如果未设置此属性，例如在 Amazon CLI 命令或 Amazon CloudFormation 模板中，`2015-10-08`则使用。有关更多信息，请参阅 [SQL 版本](iot-rule-sql-version.md)。 | 必需。 |
| 一个或多个操作 | 这些操作是在制定规则时 Amazon IoT 执行的。例如，您可以将数据插入 DynamoDB 表、将数据写入 Amazon S3 存储桶、发布至 Amazon SNS 主题或调用 Lambda 函数。 | 必需。 |
| 错误操作 | 该操作 Amazon IoT 在无法执行规则的操作时执行。 | 可选。 |
在创建 Amazon IoT 规则之前，您必须使用允许访问所需 Amazon 资源的策略创建 IAM 角色。 Amazon IoT 在实施规则时扮演这个角色。有关更多信息，请参阅[授予 Amazon IoT 规则所需的访问](https://docs.amazonaws.cn//iot/latest/developerguide/iot-create-role.html)权限和[传递角色权限](https://docs.amazonaws.cn//iot/latest/developerguide/pass-role.html)。
当您创建规则时，请注意在主题上发布的数据量。如果您创建的规则包含通配符主题模式，则这些规则可能会与您的大部分消息匹配。在这种情况下，您可能需要增加目标操作使用的 Amazon 资源的容量。我们建议在重新发布规则中避免使用通配符主题模式，以防止重复处理并降低成本。
**注意**
创建和更新规则是管理员级别操作。有权创建或更新规则的所有用户都能够访问规则处理的数据。
## 创建规则（控制台）
**创建规则 (Amazon Web Services 管理控制台)**
使用 [Amazon Web Services 管理控制台](https://console.amazonaws.cn//iot/home#/home) 命令创建规则：
1. 打开 [Amazon IoT 控制台](https://console.amazonaws.cn//iot/home#/home)。
1. 在左侧导航栏中，从**管理**部分选择**消息路由**。然后选择**规则**。
1. 在**规则**页面，选择 **创建规则**。
1. 在**指定规则属性**页面上，输入规则的名称。**规则描述**和**标签**为可选。选择**下一步**。
1. 在**配置 SQL 语句**页面上，选择 SQL 版本并输入 SQL 语句。SQL 语句的示例可以是 `SELECT temperature FROM 'iot/topic' WHERE temperature > 50`。有关更多信息，请参阅 [SQL 版本](https://docs.amazonaws.cn//iot/latest/developerguide/iot-rule-sql-version.html)和 [Amazon IoT SQL 参考](https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-reference.html)。
1. 在**附加规则操作**页面上，添加规则操作以将数据路由到其他 Amazon 服务。
1. 在**规则操作**中，从下拉列表中选择规则操作。例如，您可以选择 **Kinesis Stream**。有关规则操作的更多信息，请参阅 [Amazon IoT 规则操作](https://docs.amazonaws.cn//iot/latest/developerguide/iot-rule-actions.html)。
1. 根据您选择的规则操作，输入相关的配置详细信息。例如，如果您选择 **Kinesis Stream**，则需要选择或创建数据流资源，并选择性输入配置详细信息，例如用于在数据流中按分片对数据进行分组的**分区键**。
1. 在 **IAM 角色**中，选择或创建角色以授予对终端节点的 Amazon IoT 访问权限。请注意，这 Amazon IoT 将在您选择的 IAM 角色`aws-iot-rule`下自动创建一个前缀为的策略。您可以选择**查看**，从 IAM 控制台中查看您的 IAM 角色和策略。**错误操作**是可选的。您可以在[错误处理（错误操作）](https://docs.amazonaws.cn//iot/latest/developerguide/rule-error-handling.html)中找到更多信息。有关为您的规则创建 IAM 角色的更多信息，请参阅[授予规则所需的访问权限](https://docs.amazonaws.cn//iot/latest/developerguide/iot-create-role.html)。选择**下一步**。
1. 在**查看并创建**页面上，查看所有配置并根据需要进行编辑。选择**创建**。
成功创建规则后，您将在**规则**页面上看到列出该规则。您可以选择一个规则来打开**详细信息**页面，在该页面中可以查看规则、编辑规则、停用规则以及删除规则。
## 创建规则（CLI）
**创建规则 (Amazon CLI)**
使用 [create-topic-rule](https://docs.amazonaws.cn/cli/latest/reference/iot/create-topic-rule.html) 命令创建规则：
```
aws iot create-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
下面是一个有效载荷文件示例，其中包含将发送至 `iot/test` 主题的所有消息插入指定 DynamoDB 表的规则。SQL 语句筛选消息，ARN 角色授予写入 DynamoDB 表的 Amazon IoT 权限。
```
{
"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()}"
}
}
]
}
```
下面是一个有效载荷文件示例，其中包含将发送至 `iot/test` 主题的所有消息插入指定 S3 存储桶的规则。SQL 语句会筛选消息，而角色 ARN 则授予写入 Amazon S3 存储桶的 Amazon IoT 权限。
```
{
"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"
}
}
]
}
```
以下是载荷文件示例，其中包含将数据推送到 Amazon OpenSearch 服务的规则：
```
{
"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()}"
}
}
]
}
```
下面的有效载荷文件示例包含调用 Lambda 函数的规则：
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function"
}
}
]
}
```
下面的有效载荷文件示例包含发布至 Amazon SNS 主题的规则：
```
{
"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"
}
}
]
}
```
下面的有效载荷文件示例包含在不同 MQTT 主题上重新发布的规则：
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "my-mqtt-topic",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}
]
}
```
下面的有效载荷文件示例包含将数据推送至 Amazon Data Firehose 流的规则：
```
{
"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"
}
}
]
}
```
以下是负载文件示例，其中包含一条规则，如果 MQTT 负载中的数据被归类为 1，则使用 SageMaker Amazon AI `machinelearning_predict` 函数重新发布到主题。
```
{
"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"
}
}
]
}
```
下面是一个示例有效载荷文件，该文件包含将消息发布到 Salesforce物联网Cloud 输入流的规则。
```
{
"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"
}
}
]
}
```
下面是一个有效载荷文件示例，其中包含一个可以开始执行 Step Functions 状态机的规则。
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"stepFunctions": {
"stateMachineName": "myCoolStateMachine",
"executionNamePrefix": "coolRunning",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}
]
}
```
# 管理 Amazon IoT 规则
管理规则
您可以使用以下操作来管理您的 Amazon IoT 规则。
**Topics**
+ [
## 标记规则
](#iot-create-rule-tagging)
+ [
## 查看规则
](#iot-view-rules)
+ [
## 删除规则
](#iot-delete-rule)
## 标记规则
要为您的新规则或现有规则添加另一层特殊性，您可以应用标记。标记利用规则中的键值对，使您能够更好地控制将规则应用于资源和服务的方式和位置。 Amazon IoT 例如，您可以将规则的范围限制为仅应用于发布前测试的测试版环境 (`Key=environment, Value=beta`)，或者仅捕获从特定端点发送到 `iot/test` 主题的所有消息并将其存储在 Amazon S3 桶中。
### IAM 策略示例
有关显示如何为规则授予标记权限的示例，请考虑这样一位用户：该用户运行以下命令来创建规则，并将此规则标记为仅应用于其测试版环境。
在此示例中：
+ *MyTopicRuleName*加上规则的名称。
+ *myrule.json*加上政策文件的名称。
```
aws iot create-topic-rule
--rule-name MyTopicRuleName
--topic-rule-payload file://myrule.json
--tags "environment=beta"
```
对于本示例，您必须使用以下 IAM 策略：
****
```
{
"Version":"2012-10-17",
"Statement":
{
"Action": [ "iot:CreateTopicRule", "iot:TagResource" ],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:rule/MyTopicRuleName"
]
}
}
```
上面的示例显示了新创建的名为 `MyTopicRuleName` 的规则，该规则仅应用于您的测试版环境。策略声明中用 `MyTopicRuleName` 特别标注的 `iot:TagResource` 允许在创建或更新 `MyTopicRuleName` 时进行标记。创建规则时使用的参数 `--tags "environment=beta"` 将 `MyTopicRuleName` 的范围限制为仅您的测试版环境。如果删除参数 `--tags "environment=beta"`，则 `MyTopicRuleName` 将应用于所有环境。
有关创建特定于 Amazon IoT 规则的 IAM 角色和策略的更多信息，请参阅 [授予 Amazon IoT 规则所需的访问权限](iot-create-role.md)。
有关标记实例的一般信息，请参阅[为资源添加 Amazon IoT 标签](tagging-iot.md)。
## 查看规则
使用[list-topic-rules](https://docs.amazonaws.cn/cli/latest/reference/iot/list-topic-rules.html)命令列出您的规则：
```
aws iot list-topic-rules
```
使用[get-topic-rule](https://docs.amazonaws.cn/cli/latest/reference/iot/get-topic-rule.html)命令获取有关规则的信息：
```
aws iot get-topic-rule --rule-name myrule
```
## 删除规则
用完规则后可以将其删除。
**删除规则 (Amazon CLI)**
使用[delete-topic-rule](https://docs.amazonaws.cn/cli/latest/reference/iot/delete-topic-rule.html)命令删除规则：
```
aws iot delete-topic-rule --rule-name myrule
```
# Amazon IoT 规则动作
Amazon IoT 规则操作指定调用规则时要执行的操作。您可以定义向亚马逊 DynamoDB 数据库发送数据、向 Amazon Kinesis Data Streams 发送数据、 Amazon Lambda 调用函数等的操作。 Amazon IoT Amazon Web Services 区域 在操作的服务可用时，支持以下操作。
| 规则操作 | 说明 | API 中的名称 |
| --- | --- | --- |
| [Apache Kafka](apache-kafka-rule-action.md) | 将消息发送到 Apache Kafka 集群。 | kafka |
| [CloudWatch 警报](cloudwatch-alarms-rule-action.md) | 更改 Amazon CloudWatch 警报的状态。 | cloudwatchAlarm |
| [CloudWatch 日志](cloudwatch-logs-rule-action.md) | 向 Amazon CloudWatch Logs 发送消息。 | cloudwatchLogs |
| [CloudWatch 指标](cloudwatch-metrics-rule-action.md) | 向 CloudWatch 指标发送消息。 | cloudwatchMetric |
| [DynamoDB](dynamodb-rule-action.md) | 将消息发送到 DynamoDB 表。 | dynamoDB |
| [迪纳摩 DBv2](dynamodb-v2-rule-action.md) | 将消息数据发送到 DynamoDB 表中的多列。 | dynamoDBv2 |
| [Elasticsearch](elasticsearch-rule-action.md) | 向 OpenSearch 端点发送消息。 | OpenSearch |
| [HTTP](https-rule-action.md) | 将消息发布到 HTTPS 端点。 | http |
| [Amazon IoT Events](iotevents-rule-action.md) | 向 Amazon IoT Events 输入发送消息。 | iotEvents |
| [Amazon IoT SiteWise](iotsitewise-rule-action.md) | 向 Amazon IoT SiteWise 资产属性发送消息数据。 | iotSiteWise |
| [Firehose](kinesis-firehose-rule-action.md) | 将消息发送到 Firehose 传输流。 | firehose |
| [Kinesis Data Streams](kinesis-rule-action.md) | 将消息发送到 Kinesis 数据流。 | kinesis |
| [Lambda](lambda-rule-action.md) | 使用消息数据作为输入调用 Lambda 函数。 | lambda |
| [位置](location-rule-action.md) | 向 Amazon Location Service 发送位置数据。 | location |
| [OpenSearch](opensearch-rule-action.md) | 向亚马逊 OpenSearch 服务终端节点发送消息。 | OpenSearch |
| [重新发布](republish-rule-action.md) | 在另一个 MQTT 主题上重新发布消息。 | republish |
| [S3](s3-rule-action.md) | 将消息存储在 Amazon Simple Storage Service（Amazon S3）存储桶中。 | s3 |
| [Salesforce 物联](salesforce-iot-rule-action.md) | 将消息发送到 Salesforce物联网输入流。 | salesforce |
| [SNS](sns-rule-action.md) | 将消息发布为 Amazon Simple Notification Service（Amazon SNS）推送通知。 | sns |
| [SQS](sqs-rule-action.md) | 将消息发送到 Amazon Simple Queue Service（Amazon SQS）队列。 | sqs |
| [Step Functions](stepfunctions-rule-action.md) | 启动 Amazon Step Functions 状态机。 | stepFunctions |
| [Timestream](timestream-rule-action.md) | 将消息发送到 Amazon Timestream 数据库表。 | timestream |
**注意**
将规则定义 Amazon Web Services 区域 为与其他服务的资源相同，以便规则操作可以与该资源进行交互。
如果出现间歇性错误， Amazon IoT 规则引擎可能会多次尝试执行某项操作。如果所有尝试都失败，则该消息将被丢弃，错误将在您的 CloudWatch 日志中显示。您可以为在发生故障后调用的每条规则指定一个错误操作。有关更多信息，请参阅 [错误处理（错误操作）](rule-error-handling.md)。
某些规则操作会激活与 Amazon Key Management Service (Amazon KMS) 集成的服务中的操作，以支持静态数据加密。如果您使用客户管理 Amazon KMS key （KMS 密钥）对静态数据进行加密，则服务必须有权代表呼叫者使用 KMS 密钥。要了解如何管理客户自主管理型 KMS 密钥的权限，请参阅相应服务指南中的数据加密主题。有关客户自主管理型 KMS 密钥的更多信息，请参阅*《Amazon Key Management Service 开发人员指南》*中的 [Amazon Key Management Service 概念](https://docs.amazonaws.cn/kms/latest/developerguide/concepts.html)。
可以在错误操作的 SQL 语句中使用任何[函数](iot-sql-functions.md)或[替换模板](https://docs.amazonaws.cn//iot/latest/developerguide/iot-substitution-templates.html)，包括外部函数：[https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda](https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda)、[https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data](https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data)、[https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow](https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow)、[https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret](https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret)、[https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning](https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning)、和[https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64](https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64)。如果错误操作需要调用外部函数，则调用错误操作可能会导致产生针对外部函数的额外账单。
# Apache Kafka
Apache Kafka（Kafka）操作将消息直接发送到您的 [Amazon Managed Streaming for Apache Kafka](https://docs.amazonaws.cn//msk/latest/developerguide/what-is-msk.html)（Amazon MSK）、[Confluent Cloud](https://www.confluent.io/) 等第三方提供商托管的 Apache Kafka 集群，或自行管理的 Apache Kafka 集群。通过 Kafka 规则操作，您可以将您的物联网数据路由到 Kafka 集群。这使您能够出于各种目的构建高性能数据管道，例如流分析、数据集成、可视化和任务关键型业务应用程序等。
**注意**
本主题假设您熟悉 Apache Kafka 平台及相关概念。有关 Apache Kafka 的更多信息，请参阅 [Apache Kafka](https://kafka.apache.org/)。不支持 [MSK Serverless](https://docs.amazonaws.cn//msk/latest/developerguide/serverless.html)。MSK Serverless 集群只能通过 IAM 身份验证完成，而 Apache Kafka 规则操作目前不支持该身份验证。有关如何使用 Confluent Amazon IoT Core 进行配置的更多信息，请参阅[利用 Confluent 和 Amazon 解决物联网设备和](https://www.amazonaws.cn/blogs/apn/leveraging-confluent-and-aws-to-solve-iot-device-and-data-management-challenges/)数据管理挑战。
## 要求
此规则操作具有以下要求：
+ Amazon IoT 可以代入执行`ec2:CreateNetworkInterface`、、、、、`ec2:DescribeNetworkInterfaces``ec2:CreateNetworkInterfacePermission``ec2:DeleteNetworkInterface``ec2:DescribeSubnets``ec2:DescribeVpcs``ec2:DescribeVpcAttribute`、和`ec2:DescribeSecurityGroups`操作的 IAM 角色。此角色创建并管理您的 Amazon Virtual Private Cloud 弹性网络接口，以便联系您的 Kafka 代理。有关更多信息，请参阅 [授予 Amazon IoT 规则所需的访问权限](iot-create-role.md)。
在 Amazon IoT 控制台中，您可以选择或创建 Amazon IoT Core 允许执行此规则操作的角色。
有关网络接口的更多信息，请参阅《Amazon EC2 用户指南》**中的[弹性网络接口](https://docs.amazonaws.cn/AWSEC2/latest/UserGuide/using-eni.html)。
附加到您指定的角色的策略应如以下示例所示：
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:CreateNetworkInterfacePermission",
"ec2:DeleteNetworkInterface",
"ec2:DescribeSubnets",
"ec2:DescribeVpcs",
"ec2:DescribeVpcAttribute",
"ec2:DescribeSecurityGroups"
],
"Resource": "*"
}
]
}
```
+ 如果您使用 Amazon Secrets Manager 存储连接到 Kafka 代理所需的证书，则必须创建一个 Amazon IoT Core 可以代入执行`secretsmanager:GetSecretValue`和`secretsmanager:DescribeSecret`操作的 IAM 角色。
附加到您指定的角色的策略应如以下示例所示：
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue",
"secretsmanager:DescribeSecret"
],
"Resource": [
"arn:aws:secretsmanager:us-east-1:123456789012:secret:kafka_client_truststore-*",
"arn:aws:secretsmanager:us-east-1:123456789012:secret:kafka_keytab-*"
]
}
]
}
```
+ 您可以在 Amazon Virtual Private Cloud（Amazon VPC）中运行您的 Apache Kafka 集群。您必须创建 Apache Kafka 虚拟私有云 (VPC) 目标，并在子网中使用 NAT 网关将消息从 Amazon IoT 转发到公有 Kafka 集群。 Amazon IoT 规则引擎在目标列出的每个子网中创建一个网络接口，将流量直接路由到 VPC。当您到达目的地时， Amazon IoT 规则引擎会自动创建 VPC 规则操作。有关 VPC 规则操作的更多信息，请参阅 [Apache Kafka 虚拟私有云 (VPC) 目标](kafka-vpc-destination.md)。
+ 如果您使用客户托管 Amazon KMS key （KMS 密钥）加密静态数据，则服务必须有权代表呼叫者使用 KMS 密钥。有关更多信息，请参阅 *Amazon Managed Streaming for Apache Kafka 开发人员指南*中的 [Amazon MSK 加密](https://docs.amazonaws.cn/msk/latest/developerguide/msk-encryption.html)。
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
destinationArn
Apache Kafka 虚拟私有云 (VPC) 目标的亚马逊资源名称 (ARN)。有关创建目的地的信息，请参阅[Apache Kafka 虚拟私有云 (VPC) 目标](kafka-vpc-destination.md)。
topic
要发送到 Kafka 代理的消息的 Kafka 主题。
您可以使用替代模板替换此字段。有关更多信息，请参阅 [替换模板](iot-substitution-templates.md)。
键（可选）
Kafka 消息键。
您可以使用替代模板替换此字段。有关更多信息，请参阅 [替换模板](iot-substitution-templates.md)。
标头（可选）
您指定的 Kafka 标头的列表。每个标头都是一个键/值对，您可以在创建 Kafka 操作时指定该键值对。您可以使用这些标头将数据从物联网客户端路由到下游 Kafka 集群，而无需修改消息有效载荷。
您可以使用替代模板替换此字段。要了解如何在 Kafka 操作的标头中将内联规则的函数作为替换模板传递，请参阅[示例](#apache-kafka-rule-action-examples)。有关更多信息，请参阅 [替换模板](iot-substitution-templates.md)。
不支持二进制格式的标头。
分区（可选）
Kafka 消息分区。
您可以使用替代模板替换此字段。有关更多信息，请参阅 [替换模板](iot-substitution-templates.md)。
clientProperties
定义 Apache Kafka 生成器客户端属性的对象。
acks（可选）
生成器在考虑请求完成之前要求服务器收到的确认数。
如果指定 0 作为值，则生产者将不会等待来自服务器的任何确认。如果服务器没有收到该消息，则生成器将不会重试发送该消息。
有效值：`-1`、`0`、`1`、`all`。默认值为 `1`。
bootstrap.servers
主机和端口对列表（例如 `host1:port1`、`host2:port2`）用于建立到 Kafka 集群的初始连接。
compression.type（可选）
生成器生成的所有数据的压缩类型。
有效值：`none`、`gzip`、`snappy`、`lz4`、`zstd`。默认值为 `none`。
security.protocol
用于连接到您的 Kafka 代理的安全协议。
有效值：`SSL`、`SASL_SSL`。默认值为 `SSL`。
key.serializer
指定如何将您使用 `ProducerRecord` 提供的键对象转换为字节。
有效值：`StringSerializer`。
value.serializer
指定如何将您使用 `ProducerRecord` 提供的值对象转换为字节。
有效值：`ByteBufferSerializer`。
ssl.truststore
base64 格式的信任库文件或位于 [Amazon Secrets Manager](https://docs.amazonaws.cn/secretsmanager/latest/userguide/) 的信任库文件位置。如果您的信任存储受到 Amazon 证书授权机构（CA）的认证，则不需要此值。
此字段支持替换模板。如果使用 Secrets Manager 存储连接到 Kafka 代理所需的凭证，则可以使用 `get_secret` SQL 函数检索此字段的值。有关替换模板的更多信息，请参阅 [替换模板](iot-substitution-templates.md)。有关 `get_secret` SQL 函数的更多信息，请参阅[get\$1secret(secretId, secretType, key, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret)。如果信任库采用文件的形式，请使用 `SecretBinary` 参数。如果信任库采用字符串的形式，请使用 `SecretString` 参数。
此值最大为 65 KB。
ssl.truststore.password
信任库存储的密码。仅当您为信任库创建了密码时，才需要此值。
ssl.keystore
密钥库文件。当您指定 `SSL` 作为 `security.protocol` 的值时，才需要此值。
此字段支持替换模板。使用 Secrets Manager 来存储连接到您的 Kafka 代理所需的凭证。要检索此字段的值，请使用 `get_secret` SQL 函数。有关替换模板的更多信息，请参阅 [替换模板](iot-substitution-templates.md)。有关 `get_secret` SQL 函数的更多信息，请参阅[get\$1secret(secretId, secretType, key, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret)。使用 `SecretBinary` 参数。
ssl.keystore.password
密钥库文件存储的密码。如果为 `ssl.keystore` 指定了值，则需要此值。
此字段的值可以是纯文本。此字段还支持替代模板。使用 Secrets Manager 来存储连接到您的 Kafka 代理所需的凭证。要检索此字段的值，请使用 `get_secret` SQL 函数。有关替换模板的更多信息，请参阅 [替换模板](iot-substitution-templates.md)。有关 `get_secret` SQL 函数的更多信息，请参阅[get\$1secret(secretId, secretType, key, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret)。使用 `SecretString` 参数。
ssl.key.password
密钥库文件中私有密钥的密码。
此字段支持替换模板。使用 Secrets Manager 来存储连接到您的 Kafka 代理所需的凭证。要检索此字段的值，请使用 `get_secret` SQL 函数。有关替换模板的更多信息，请参阅 [替换模板](iot-substitution-templates.md)。有关 `get_secret` SQL 函数的更多信息，请参阅[get\$1secret(secretId, secretType, key, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret)。使用 `SecretString` 参数。
sasl.mechanism
用于连接到您的 Kafka 代理的安全机制。当您为 `security.protocol` 指定 `SASL_SSL` 时，则需要此值。
有效值：`PLAIN`、`SCRAM-SHA-512`、`GSSAPI`。
`SCRAM-SHA-512`是 cn-north-1、cn-northwest-1、-1 和 -1 区域中唯一支持的安全机制。 us-gov-east us-gov-west
sasl.plain.username
用于从 Secrets Manager 中检索密钥字符串的用户名。当您为 `security.protocol` 指定 `SASL_SSL`、为 `sasl.mechanism` 指定 `PLAIN` 时，则需要此值。
sasl.plain.password
用于从 Secrets Manager 中检索密钥字符串的密码。当您为 `security.protocol` 指定 `SASL_SSL`、为 `sasl.mechanism` 指定 `PLAIN` 时，则需要此值。
sasl.scram.username
用于从 Secrets Manager 中检索密钥字符串的用户名。当您为 `security.protocol` 指定 `SASL_SSL`、为 `sasl.mechanism` 指定 `SCRAM-SHA-512` 时，则需要此值。
sasl.scram.password
用于从 Secrets Manager 中检索密钥字符串的密码。当您为 `security.protocol` 指定 `SASL_SSL`、为 `sasl.mechanism` 指定 `SCRAM-SHA-512` 时，则需要此值。
sasl.kerberos.keytab
Secrets Manager 中用于 Kerberos 身份验证的 keytab 文件。当您为 `security.protocol` 指定 `SASL_SSL`、为 `sasl.mechanism` 指定 `GSSAPI` 时，则需要此值。
此字段支持替换模板。使用 Secrets Manager 来存储连接到您的 Kafka 代理所需的凭证。要检索此字段的值，请使用 `get_secret` SQL 函数。有关替换模板的更多信息，请参阅 [替换模板](iot-substitution-templates.md)。有关 `get_secret` SQL 函数的更多信息，请参阅[get\$1secret(secretId, secretType, key, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret)。使用 `SecretBinary` 参数。
sasl.kerberos.service.name
Apache Kafka 运行的 Kerberos 主要名称。当您为 `security.protocol` 指定 `SASL_SSL`、为 `sasl.mechanism` 指定 `GSSAPI` 时，则需要此值。
sasl.kerberos.krb5.kdc
您的 Apache Kafka 生成器客户端连接到的密钥分配中心（KDC）的主机名。当您为 `security.protocol` 指定 `SASL_SSL`、为 `sasl.mechanism` 指定 `GSSAPI` 时，则需要此值。
sasl.kerberos.krb5.realm
您的 Apache Kafka 生成器客户端连接到的领域。当您为 `security.protocol` 指定 `SASL_SSL`、为 `sasl.mechanism` 指定 `GSSAPI` 时，则需要此值。
sasl.kerberos.principal
Kerberos 可以为其分配票证以访问 Kerberos 感知服务的唯一 Kerberos 身份。当您为 `security.protocol` 指定 `SASL_SSL`、为 `sasl.mechanism` 指定 `GSSAPI` 时，则需要此值。
## 示例
以下 JSON 示例在规则中定义了 Apache Kafka 操作。 Amazon IoT 以下示例将 [sourceIp()](iot-sql-functions.md#iot-function-sourceip) 内联函数作为[替换模板](https://docs.amazonaws.cn//iot/latest/developerguide/iot-substitution-templates.html)传递到 Kafka 操作标头中。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"kafka": {
"destinationArn": "arn:aws:iot:region:123456789012:ruledestination/vpc/VPCDestinationARN",
"topic": "TopicName",
"clientProperties": {
"bootstrap.servers": "kafka.com:9092",
"security.protocol": "SASL_SSL",
"ssl.truststore": "${get_secret('kafka_client_truststore', 'SecretBinary','arn:aws:iam::123456789012:role/kafka-get-secret-role-name')}",
"ssl.truststore.password": "kafka password",
"sasl.mechanism": "GSSAPI",
"sasl.kerberos.service.name": "kafka",
"sasl.kerberos.krb5.kdc": "kerberosdns.com",
"sasl.kerberos.keytab": "${get_secret('kafka_keytab','SecretBinary', 'arn:aws:iam::123456789012:role/kafka-get-secret-role-name')}",
"sasl.kerberos.krb5.realm": "KERBEROSREALM",
"sasl.kerberos.principal": "kafka-keytab/kafka-keytab.com"
},
"headers": [
{
"key": "static_header_key",
"value": "static_header_value"
},
{
"key": "substitutable_header_key",
"value": "${value_from_payload}"
},
{
"key": "source_ip",
"value": "${sourceIp()}"
}
]
}
}
]
}
}
```
**有关 Kerberos 设置的重要注意事项**
+ 您的密钥分配中心（KDC）必须通过目标 VPC 内的私有域名系统（DNS）进行解析。一种可能的方法是将 KDC DNS 条目添加到私有托管区域。有关此方法的更多信息，请参阅[如何使用私有托管区域](https://docs.amazonaws.cn/Route53/latest/DeveloperGuide/hosted-zones-private.html)。
+ 每个 VPC 都必须启用 DNS 解析。有关更多信息，请参阅[将 DNS 与您的 VPC 一起使用](https://docs.amazonaws.cn/vpc/latest/userguide/vpc-dns.html)。
+ VPC 目标中的网络接口安全组和实例级安全组必须允许来自 VPC 内部以下端口的流量。
+ 引导代理侦听器端口上的 TCP 流量（通常为 9092，但必须在 9000–9100 范围内）
+ KDC 端口 88 上的 TCP 和 UDP 流量
+ `SCRAM-SHA-512`是 cn-north-1、cn-northwest-1、-1 和 -1 区域中唯一支持的安全机制。 us-gov-east us-gov-west
# Apache Kafka 虚拟私有云 (VPC) 目标
Apache Kafka 规则操作将数据路由到 Amazon Virtual Private Cloud（Amazon VPC）中的 Apache Kafka 集群。当您为规则操作指定 VPC 目标时，将自动启用 Apache Kafka 规则操作使用的 VPC 配置。
Apache Kafka 虚拟私有云 (VPC) 目标包含 VPC 内的子网列表。规则引擎将在您在此列表中指定的每个子网中创建一个弹性网络接口。有关网络接口的更多信息，请参阅 Amazon EC2 用户指南中的[弹性网络接口](https://docs.amazonaws.cn/AWSEC2/latest/UserGuide/using-eni.html)。
## 要求和注意事项
+ 如果您使用的是自我管理的 Apache Kafka 集群，则将在互联网上使用公有端点访问此集群：
+ 为子网中的实例创建 NAT 网关。NAT 网关具有可以连接到互联网的公有 IP 地址，这允许规则引擎将您的消息转发到公有 Kafka 集群。
+ 使用由 Apache Kafka Virtual Private Cloud (VPCENIs) 目标创建的弹性网络接口 () 分配弹性 IP 地址。必须将您使用的安全组配置为阻止传入流量。
**注意**
如果 Apache Kafka 虚拟私有云 (VPC) 目标被禁用然后又重新启用，则必须将弹性云与新的目标重新关联。 IPs ENIs
+ 如果 Apache Kafka 虚拟私有云 (VPC) 目标连续 30 天没有收到任何流量，则该目标将被禁用。
+ 如果 Apache Kafka 虚拟私有云 (VPC) 目标使用的任何资源发生变化，则该目标将被禁用且无法使用。
+ 一些可以禁用 Apache Kafka 虚拟私有云 (VPC) 目标的更改包括：
+ 删除 VPC、子网、安全组或使用的角色。
+ 修改角色使其不再拥有必要的权限。
+ 接近子网容量，这使我们无法应用 [FedRAMP 补丁](https://www.amazonaws.cn/compliance/fedramp/)。
+ 禁用目的地。
## 定价
出于定价目的，除了在资源位于您的 VPC 中时向资源发送消息的操作之外，还会计量 VPC 规则操作。有关定价信息，请参阅 [Amazon IoT Core 定价](https://www.amazonaws.cn/iot-core/pricing/)。
## 创建 Apache Kafka 虚拟私有云 (VPC) 目标
您可以使用 API 或控制台创建 Apache Kafka 虚拟私有云 (VPC) 目标。[CreateTopicRuleDestination](https://docs.amazonaws.cn/iot/latest/apireference/API_CreateTopicRuleDestination.html) Amazon IoT Core
创建目标时，必须指定以下信息。
vpcId
亚马逊 VPC 的唯一 ID。
subnetIds
规则引擎在其中创建弹性网络接口的子网列表。规则引擎为列表中的每个子网分配一个网络接口。
securityGroups（可选）
要应用到网络接口的安全组列表。
roleArn
有权代表您创建网络接口的角色的 Amazon 资源名称（ARN）。
此 ARN 应附加一个类似于以下示例的策略。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeVpcs",
"ec2:DeleteNetworkInterface",
"ec2:DescribeSubnets",
"ec2:DescribeVpcAttribute",
"ec2:DescribeSecurityGroups"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "ec2:CreateNetworkInterfacePermission",
"Resource": "*",
"Condition": {
"StringEquals": {
"ec2:ResourceTag/VPCDestinationENI": "true"
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface",
"aws:RequestTag/VPCDestinationENI": "true"
}
}
}
]
}
```
### 使用创建 Apache Kafka 虚拟私有云 (VPC) 目标 Amazon CLI
以下示例说明如何使用创建目的地 Amazon CLI。
```
aws --region regions iot create-topic-rule-destination --destination-configuration 'vpcConfiguration={subnetIds=["subnet-123456789101230456"],securityGroups=[],vpcId="vpc-123456789101230456",roleArn="arn:aws:iam::123456789012:role/role-name"}'
```
运行此命令后，目标状态将为`IN_PROGRESS`。几分钟后，其状态将更改为 `ERROR`（如果命令不成功）或 `ENABLED`。当目标状态为 `ENABLED` 时，目标即可使用。
您可以使用以下命令获取 Apache Kafka 虚拟私有云 (VPC) 目标的状态。
```
aws --region region iot get-topic-rule-destination --arn "VPCDestinationARN"
```
### 使用控制台创建 Apache Kafka 虚拟私有云 (VPC) 目标 Amazon IoT Core
以下步骤介绍如何使用 Amazon IoT Core 控制台创建目的地。
1. 导航到 Amazon IoT Core 控制台。在左侧窗格的**操作**选项卡上，选择**目标**。
1. 输入以下字段的值。
+ ** - VPC ID**
+ **子网 IDs**
+ **安全组**
1. 选择具有创建网络接口所需权限的角色。前面的示例策略包含这些权限。
当 Apache Kafka Virtual Private Cloud (VPC) 目标状态为 “**已启用**” 时，它就可以使用了。
# CloudWatch 警报
CloudWatch 警报 (`cloudWatchAlarm`) 操作会更改 Amazon CloudWatch 警报的状态。您可以在此调用中指定状态更改原因和状态值。
## 要求
此规则操作具有以下要求：
+ Amazon IoT 可以代入执行`cloudwatch:SetAlarmState`操作的 IAM 角色。有关更多信息，请参阅 [授予 Amazon IoT 规则所需的访问权限](iot-create-role.md)。
在 Amazon IoT 控制台中，您可以选择或创建 Amazon IoT 允许执行此规则操作的角色。
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
`alarmName`
CloudWatch 警报名称。
仅支持[替换模板](iot-substitution-templates.md)：API 且 Amazon CLI 仅支持
`stateReason`
警报更改的原因。
支持[替换模板](iot-substitution-templates.md)：是
`stateValue`
警报状态的值。有效值：`OK`、`ALARM`、`INSUFFICIENT_DATA`。
支持[替换模板](iot-substitution-templates.md)：是
`roleArn`
允许访问 CloudWatch 警报的 IAM 角色。有关更多信息，请参阅 [要求](#cloudwatch-alarms-rule-action-requirements)。
支持[替换模板](iot-substitution-templates.md)：否
## 示例
以下 JSON 示例定义了 Amazon IoT 规则中的 CloudWatch 警报操作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchAlarm": {
"alarmName": "IotAlarm",
"stateReason": "Temperature stabilized.",
"stateValue": "OK",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw"
}
}
]
}
}
```
## 另请参阅
+ [什么是亚马逊 CloudWatch？](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/) 在 *Amazon CloudWatch 用户指南*中
+ [使用亚马逊* CloudWatch 用户指南中的亚马逊 CloudWatch*警报](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)
# CloudWatch 日志
日 CloudWatch 志 (`cloudwatchLogs`) 操作将数据发送到 Amazon CloudWatch 日志。您可以使用 `batchMode` 在一条消息中上载多条设备日志记录并为其加上时间戳。您还可以指定操作要向其发送数据的日志组。
## 要求
此规则操作具有以下要求：
+ Amazon IoT 可以代入执行`logs:CreateLogStream``logs:DescribeLogStreams`、和`logs:PutLogEvents`操作的 IAM 角色。有关更多信息，请参阅 [授予 Amazon IoT 规则所需的访问权限](iot-create-role.md)。
在 Amazon IoT 控制台中，您可以选择或创建 Amazon IoT 允许执行此规则操作的角色。
+ 如果您使用客户托管 Amazon KMS key （KMS 密钥）对日志中的 CloudWatch 日志数据进行加密，则该服务必须有权代表调用方使用 KMS 密钥。有关更多信息，请参阅 *Amazon CloudWatch 日志用户指南 Amazon KMS中的使用加密 CloudWatch 日志*[中的日志数据](https://docs.amazonaws.cn/AmazonCloudWatch/latest/logs/encrypt-log-data-kms.html)。
## `batchMode` 的 MQTT 消息格式要求
如果您在`batchMode`关闭的情况下使用 CloudWatch 日志规则操作，则没有 MQTT 消息格式要求。（注意：`batchMode` 参数的默认值为 `false`。） 但是，如果您在`batchMode`开启的情况下使用 CloudWatch 日志规则操作（参数值为`true`），则包含设备端日志的 MQTT 消息必须格式化为包含时间戳和消息负载。**注意：**`timestamp` 表示事件发生的时间，以自 1970 年 1 月 1 日 00:00:00 UTC 之后的毫秒数表示。
以下为发布格式的示例：
```
[
{"timestamp": 1673520691093, "message": "Test message 1"},
{"timestamp": 1673520692879, "message": "Test message 2"},
{"timestamp": 1673520693442, "message": "Test message 3"}
]
```
根据生成设备端日志的方式，在发送这些日志之前，可能需要对其进行筛选和重新格式化，以符合此要求。有关更多信息，请参阅 [MQTT 消息有效载荷](https://docs.amazonaws.cn/iot/latest/developerguide/topicdata.html)。
与`batchMode`参数无关，`message`内容必须符合 Amazon IoT 消息大小限制。有关更多信息，请参阅 [Amazon IoT Core 终端节点和限额](https://docs.amazonaws.cn/general/latest/gr/iot-core.html)。
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
`logGroupName`
操作发送数据的 CloudWatch 日志组。
仅支持[替换模板](iot-substitution-templates.md)：API 且 Amazon CLI 仅支持
`roleArn`
允许访问 CloudWatch 日志组的 IAM 角色。有关更多信息，请参阅 [要求](#cloudwatch-logs-rule-action-requirements)。
支持[替换模板](iot-substitution-templates.md)：否
（可选）`batchMode`
表示是否将批量日志记录提取并上传到 CloudWatch。值包括 `true` 或 `false`（默认值）。有关更多信息，请参阅 [要求](#cloudwatch-logs-rule-action-requirements)。
支持[替换模板](iot-substitution-templates.md)：否
## 示例
以下 JSON 示例在 Amazon IoT 规则中定义了 “ CloudWatch 日志” 操作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchLogs": {
"logGroupName": "IotLogs",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw",
"batchMode": false
}
}
]
}
}
```
## 另请参阅
+ [什么是 Amazon CloudWatch 日志？](https://docs.amazonaws.cn/AmazonCloudWatch/latest/logs/) 在 *Amazon CloudWatch 日志用户指南*中
# CloudWatch 指标
CloudWatch 指标 (`cloudwatchMetric`) 操作捕获 Amazon 的 CloudWatch指标。您可以指定指标命名空间、名称、值、单位和时间戳。
## 要求
此规则操作具有以下要求：
+ Amazon IoT 可以代入执行`cloudwatch:PutMetricData`操作的 IAM 角色。有关更多信息，请参阅 [授予 Amazon IoT 规则所需的访问权限](iot-create-role.md)。
在 Amazon IoT 控制台中，您可以选择或创建 Amazon IoT 允许执行此规则操作的角色。
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
`metricName`
CloudWatch 指标名称。
支持[替换模板](iot-substitution-templates.md)：是
`metricNamespace`
CloudWatch 指标命名空间名称。
支持[替换模板](iot-substitution-templates.md)：是
`metricUnit`
支持的公制单位 CloudWatch。
支持[替换模板](iot-substitution-templates.md)：是
`metricValue`
包含 CloudWatch 指标值的字符串。
支持[替换模板](iot-substitution-templates.md)：是
`metricTimestamp`
（可选）包含用 Unix 纪元时间表示的 timestamp（以秒为单位）的字符串。默认为当前 Unix 纪元时间。
支持[替换模板](iot-substitution-templates.md)：是
`roleArn`
允许访问 CloudWatch 指标的 IAM 角色。有关更多信息，请参阅 [要求](#cloudwatch-metrics-rule-action-requirements)。
支持[替换模板](iot-substitution-templates.md)：否
## 示例
以下 JSON 示例定义了 Amazon IoT 规则中的 CloudWatch 指标操作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchMetric": {
"metricName": "IotMetric",
"metricNamespace": "IotNamespace",
"metricUnit": "Count",
"metricValue": "1",
"metricTimestamp": "1456821314",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw"
}
}
]
}
}
```
以下 JSON 示例定义了在 Amazon IoT 规则中使用替换模板的 CloudWatch 指标操作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchMetric": {
"metricName": "${topic()}",
"metricNamespace": "${namespace}",
"metricUnit": "${unit}",
"metricValue": "${value}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw"
}
}
]
}
}
```
## 另请参阅
+ [什么是亚马逊 CloudWatch？](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/) 在 *Amazon CloudWatch 用户指南*中
+ [使用亚马逊* CloudWatch 用户指南中的亚马逊 CloudWatch*指标](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/working_with_metrics.html)
# DynamoDB
DynamoDB (`dynamoDB`) 操作可将所有或部分 MQTT 消息写入 Amazon DynamoDB 表。
您可以按照教程执行操作，该教程向您说明如何使用 DynamoDB 操作创建并测试规则。有关更多信息，请参阅 [教程：将设备数据存储在 DynamoDB 表中](iot-ddb-rule.md)。
**注意**
此规则将非 JSON 数据作为二进制数据写入到 DynamoDB 中。DynamoDB 控制台以 Base64 编码文本格式显示数据。
## 要求
此规则操作具有以下要求：
+ Amazon IoT 可以代入执行`dynamodb:PutItem`操作的 IAM 角色。有关更多信息，请参阅 [授予 Amazon IoT 规则所需的访问权限](iot-create-role.md)。
在 Amazon IoT 控制台中，您可以选择或创建 Amazon IoT 允许执行此规则操作的角色。
+ 如果您使用客户托管 Amazon KMS key （KMS 密钥）对 DynamoDB 中的静态数据进行加密，则该服务必须有权代表调用方使用 KMS 密钥。有关更多信息，请参阅 *Amazon DynamoDB 入门指南*中的[客户托管式 KMS](https://docs.amazonaws.cn/amazondynamodb/latest/developerguide/encryption.howitworks.html#managed-cmk-customer-managed)。
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
`tableName`
DynamoDB 表的名称。
仅支持[替换模板](iot-substitution-templates.md)：API 且 Amazon CLI 仅支持
`hashKeyField`
哈希键（也称为分区键）的名称。
仅支持[替换模板](iot-substitution-templates.md)：API 且 Amazon CLI 仅支持
`hashKeyType`
（可选）哈希键（也称为分区键）的数据类型。有效值：`STRING`、`NUMBER`。
仅支持[替换模板](iot-substitution-templates.md)：API 且 Amazon CLI 仅支持
`hashKeyValue`
哈希键的值。考虑使用替代模板，例如 `${topic()}` 或者 `${timestamp()}`。
支持[替换模板](iot-substitution-templates.md)：是
`rangeKeyField`
（可选）范围键（也称为排序键）的名称。
仅支持[替换模板](iot-substitution-templates.md)：API 且 Amazon CLI 仅支持
`rangeKeyType`
（可选）范围键（也称为排序键）的数据类型。有效值：`STRING`、`NUMBER`。
仅支持[替换模板](iot-substitution-templates.md)：API 且 Amazon CLI 仅支持
`rangeKeyValue`
（可选）范围键的值。考虑使用替代模板，例如 `${topic()}` 或者 `${timestamp()}`。
支持[替换模板](iot-substitution-templates.md)：是
`payloadField`
（可选）有效载荷将写入的列的名称。如果省略此值，有效载荷将写入 `payload` 列。
支持[替换模板](iot-substitution-templates.md)：是
`operation`
（可选）要执行的操作类型。有效值：`INSERT`、`UPDATE`、`DELETE`。
支持[替换模板](iot-substitution-templates.md)：是
`roleARN`
允许访问 DynamoDB 表的 IAM 角色。有关更多信息，请参阅 [要求](#dynamodb-rule-action-requirements)。
支持[替换模板](iot-substitution-templates.md)：否
写入 DynamoDB 表的数据是规则的 SQL 语句的结果。
## 示例
以下 JSON 示例在规则中定义了 DynamoDB 操作。 Amazon IoT
```
{
"topicRulePayload": {
"sql": "SELECT * AS message FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"dynamoDB": {
"tableName": "my_ddb_table",
"hashKeyField": "key",
"hashKeyValue": "${topic()}",
"rangeKeyField": "timestamp",
"rangeKeyValue": "${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDB"
}
}
]
}
}
```
## 另请参阅
+ *Amazon DynamoDB 开发人员指南*中的[什么是 DynamoDB？](https://docs.amazonaws.cn/amazondynamodb/latest/developerguide/)
+ *Amazon DynamoDB 开发人员指南*中的 [DynamoDB 入门](https://docs.amazonaws.cn/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html)
+ [教程：将设备数据存储在 DynamoDB 表中](iot-ddb-rule.md)
# 迪纳摩 DBv2
Dynamo DBv2 (`dynamoDBv2`) 操作将 MQTT 消息的全部或部分写入亚马逊 DynamoDB 表。有效载荷中的每个属性将写入 DynamoDB 数据库中的单独一列。
## 要求
此规则操作具有以下要求：
+ Amazon IoT 可以代入执行`dynamodb:PutItem`操作的 IAM 角色。有关更多信息，请参阅 [授予 Amazon IoT 规则所需的访问权限](iot-create-role.md)。
在 Amazon IoT 控制台中，您可以选择或创建 Amazon IoT 允许执行此规则操作的角色。
+ 如果要定义 MQTT 消息有效载荷，则它必须包含一个与表的主分区键相匹配的根级键，以及一个与表的主排序键相匹配的根级键。
+ 如果您使用客户托管 Amazon KMS key （KMS 密钥）对 DynamoDB 中的静态数据进行加密，则该服务必须有权代表调用方使用 KMS 密钥。有关更多信息，请参阅 *Amazon DynamoDB 入门指南*中的[客户托管式 KMS](https://docs.amazonaws.cn/amazondynamodb/latest/developerguide/encryption.howitworks.html#managed-cmk-customer-managed)。
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
`putItem`
用于指定消息数据将写入的 DynamoDB 表的对象。该对象必须具备以下信息：
`tableName`
DynamoDB 表的名称。
仅支持[替换模板](iot-substitution-templates.md)：API 且 Amazon CLI 仅支持
`roleARN`
允许访问 DynamoDB 表的 IAM 角色。有关更多信息，请参阅 [要求](#dynamodb-v2-rule-action-requirements)。
支持[替换模板](iot-substitution-templates.md)：否
写入 DynamoDB 表的数据是规则的 SQL 语句的结果。
## 示例
以下 JSON 示例在 Amazon IoT 规则中定义了 Dynamo DBv2 操作。
```
{
"topicRulePayload": {
"sql": "SELECT * AS message FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"dynamoDBv2": {
"putItem": {
"tableName": "my_ddb_table"
},
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDBv2",
}
}
]
}
}
```
以下 JSON 示例定义了在规则中使用替换模板的 DynamoDB 操作。 Amazon IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2015-10-08",
"actions": [
{
"dynamoDBv2": {
"putItem": {
"tableName": "${topic()}"
},
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDBv2"
}
}
]
}
}
```
## 另请参阅
+ *Amazon DynamoDB 开发人员指南*中的[什么是 DynamoDB？](https://docs.amazonaws.cn/amazondynamodb/latest/developerguide/)
+ *Amazon DynamoDB 开发人员指南*中的 [DynamoDB 入门](https://docs.amazonaws.cn/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html)
# Elasticsearch
Elasticsearch (`elasticsearch`) 操作将来自 MQTT 消息的数据写入亚马逊 OpenSearch 服务域。然后，您可以使用 OpenSearch 仪表板等工具在 Ser OpenSearch vice 中查询和可视化数据。
**警告**
`Elasticsearch` 操作只能由现有规则操作使用。要创建新的规则操作或更新现有规则操作，请使用 `OpenSearch` 规则而不是操作。有关更多信息，请参阅 [OpenSearch](opensearch-rule-action.md)。
## 要求
此规则操作具有以下要求：
+ Amazon IoT 可以代入执行`es:ESHttpPut`操作的 IAM 角色。有关更多信息，请参阅 [授予 Amazon IoT 规则所需的访问权限](iot-create-role.md)。
在 Amazon IoT 控制台中，您可以选择或创建 Amazon IoT 允许执行此规则操作的角色。
+ 如果您使用客户托管 Amazon KMS key （KMS 密钥）加密中的静态数据 OpenSearch，则该服务必须有权代表呼叫者使用 KMS 密钥。有关更多信息，请参阅[《亚马逊服务*开发者指南》*中的亚马逊 OpenSearch 服务静态数据加密](https://docs.amazonaws.cn/opensearch-service/latest/developerguide/encryption-at-rest.html)。 OpenSearch
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
`endpoint`
您的服务域端点。
仅支持[替换模板](iot-substitution-templates.md)：API 且 Amazon CLI 仅支持
`index`
您要在其中存储数据的索引。
支持[替换模板](iot-substitution-templates.md)：是
`type`
您存储的文档类型。
支持[替换模板](iot-substitution-templates.md)：是
`id`
每个文档的唯一标识符。
支持[替换模板](iot-substitution-templates.md)：是
`roleARN`
允许访问 OpenSearch 服务域的 IAM 角色。有关更多信息，请参阅 [要求](#elasticsearch-rule-action-requirements)。
支持[替换模板](iot-substitution-templates.md)：否
## 示例
以下 JSON 示例定义了 Amazon IoT 规则中的 Elasticsearch 操作以及如何为该`elasticsearch`操作指定字段。有关更多信息，请参阅 [ElasticsearchAction](https://docs.amazonaws.cn/iot/latest/apireference/API_ElasticsearchAction.html)。
```
{
"topicRulePayload": {
"sql": "SELECT *, timestamp() as timestamp FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"elasticsearch": {
"endpoint": "https://my-endpoint",
"index": "my-index",
"type": "my-type",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_es"
}
}
]
}
}
```
以下 JSON 示例定义了一个在规则中使用替换模板的 Elasticsearch 操作。 Amazon IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"elasticsearch": {
"endpoint": "https://my-endpoint",
"index": "${topic()}",
"type": "${type}",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_es"
}
}
]
}
}
```
## 另请参阅
+ [OpenSearch](opensearch-rule-action.md)
+ [什么是亚马逊 OpenSearch 服务？](https://docs.amazonaws.cn/opensearch-service/latest/developerguide/)
# HTTP
HTTPS (`http`) 操作将数据从 MQTT 消息发送到 HTTPS 终端节点，该终端节点可以指向 Web 应用程序或服务。
## 要求
此规则操作具有以下要求：
+ 您必须先确认并启用 HTTPS 端点，然后规则引擎才能使用它们。有关更多信息，请参阅 [HTTP 操作目的地](http-action-destination.md)。
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
`url`
使用 HTTP POST 方法发送消息的 HTTPS 端点。如果使用 IP 地址代替主机名，则必须是 IPv4 地址。 IPv6 不支持地址。
支持[替换模板](iot-substitution-templates.md)：是
`confirmationUrl`
（可选）如果指定，则 Amazon IoT 使用确认 URL 创建匹配的主题规则目标。在 HTTP 操作中使用 HTTP 操作目标之前，必须将其启用。有关更多信息，请参阅 [HTTP 操作目的地](http-action-destination.md)。如果您使用替换模板，则必须先手动创建 HTTP 操作目标，然后才能使用该`http`操作。 `confirmationUrl`前缀必须为`url`。
`url` 和 `confirmationUrl` 之间的关系由以下内容描述：
+ 如果`url`是硬编码且`confirmationUrl`未提供，则我们会隐式地将该`url`字段视为. `confirmationUrl` Amazon IoT 为创建主题规则目标`url`。
+ 如果`url`和`confirmationUrl`是硬编码，则`url`必须以开头。`confirmationUrl` Amazon IoT 为创建主题规则目标`confirmationUrl`。
+ 如果 `url` 包含替换模板，则必须指定 `confirmationUrl` 并且 `url` 必须以 `confirmationUrl` 开头。如果`confirmationUrl`包含替换模板，则必须先手动创建 HTTP 操作目标，然后才能使用该`http`操作。如果`confirmationUrl`不包含替换模板，则为 Amazon IoT 创建主题规则目标`confirmationUrl`。
支持[替换模板](iot-substitution-templates.md)：是
`headers`
（可选）要包含在对端点的 HTTP 请求中的标头列表。每个标头都必须包含以下信息：
`key`
标头的键。
支持[替换模板](iot-substitution-templates.md)：否
`value`
标头的值。
支持[替换模板](iot-substitution-templates.md)：是
当有效负载为 JSON 格式 application/json 时，默认内容类型为。否则，它是 application/octet-stream。您可以在标头中，使用键内容类型（不区分大小写）指定确切的内容类型来覆盖它。
`auth`
（可选）规则引擎在连接到 `url` 参数中指定的端点 URL 时使用的身份验证。目前，Signature Version 4 是唯一支持的身份验证类型。有关更多信息，请参阅 [HTTP 授权](https://docs.amazonaws.cn/iot/latest/apireference/API_HttpAuthorization.html)。
支持[替换模板](iot-substitution-templates.md)：否
`enableBatching`
（可选）是否将 HTTP 操作消息处理成对给定网址的单个请求。值可以是真或假。有关批处理的更多信息，请参阅[批处理 HTTP 操作消息](http_batching.md)。
布尔值
支持[替换模板](iot-substitution-templates.md)：否
`batchConfig`
（可选）批处理的配置设置。启用后，必须指定`batchConfig`参数。如果未指定`batchConfig`参数，则将使用默认值。
`maxBatchOpenMs`
传出消息等待其他消息创建批次的最长时间（以毫秒为单位）。设置越高，批处理 HTTP 操作的延迟时间就越长。
最小值：5 毫秒。最大值：200 毫秒。
默认值：20 毫秒
支持[替换模板](iot-substitution-templates.md)：否
`maxBatchSize`
在单个操作执行中批处理的最大消息数。
支持[替换模板](iot-substitution-templates.md)：否
最小值：2 条消息。最大值：10 条消息
默认值：10 条消息
`maxBatchSizeBytes`
消息批处理的最大大小，以字节为单位。
最小值：100 字节。最大值：131,072 字节
默认值：5,120 字节
支持[替换模板](iot-substitution-templates.md)：否
当有效负载为 JSON 格式 application/json 时，默认内容类型为。否则，它是 application/octet-stream。您可以在标头中，使用键内容类型（不区分大小写）指定确切的内容类型来覆盖它。
## 示例
以下 JSON 示例定义了一 Amazon IoT 条带有 HTTP 操作的规则。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"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}"
}
]
}
}
]
}
}
```
```
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com",
"headers": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"enableBatching": true,
"batchConfig": {
"maxBatchOpenMs": 123,
"maxBatchSize": 5,
"maxBatchSizeBytes": 131072,
}
},
"errorAction": {
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com"
// batchConfig is not allowed here
}
}
```
## HTTP 操作重试逻辑
Amazon IoT 规则引擎将根据以下规则重试 HTTP 操作：
+ 规则引擎尝试至少发送一次消息。
+ 规则引擎最多重试两次。最大尝试次数为三次。
+ 在下列情况中，规则引擎不会尝试重试：
+ 之前的尝试提供了大于 16384 字节的响应。
+ 下游 Web 服务或应用程序在尝试之后关闭了 TCP 连接。
+ 完成包括重试在内的请求总用时超过了请求超时限制。
+ 该请求返回除 429、500-599 之外的 HTTP 状态代码。
**注意**
[标准数据传输费用](https://www.amazonaws.cn/ec2/pricing/on-demand/)适用于重试操作。
## 另请参阅
+ [批处理 HTTP 操作消息](http_batching.md)
+ [HTTP 操作目的地](http-action-destination.md)
+ 通过 Amazon博客*上的物联网将数据直接路由 Amazon IoT Core 到您的* [Web 服务](https://www.amazonaws.cn/blogs/iot/route-data-directly-from-iot-core-to-your-web-services/)
# 批处理 HTTP 操作消息
您可以使用批处理在单个请求中发送多个 HTTP 操作消息。
## 概述
批处理使您可以将消息从 Amazon IoT Core 规则引擎批量发送到您的 HTTP 终端节点。此功能可通过减少 HTTP 操作执行次数来帮助您降低成本，并通过减少与建立新连接相关的开销来提高效率。
**注意**
批处理的 HTTP 操作按单个操作计量。根据 Amazon IoT Core 规则引擎向下游服务发射的出站批处理有效载荷的大小，以 5 KiB 为增量进行计量。有关更多信息，请参阅 [Amazon IoT Core 价格页面](https://www.amazonaws.cn/iot-core/pricing/)。
当您在物联网规则操作的定义中启用批处理时，将可以使用以下参数进行配置：
`maxBatchOpenMs`
传出消息等待其他消息创建批次的最长时间（以毫秒为单位）。设置越高，批处理 HTTP 操作的延迟时间就越长。
最小值：5 毫秒。最大值：200 毫秒。
默认值：20 毫秒
支持[替换模板](iot-substitution-templates.md)：否
`maxBatchSize`
在单个 IoT 规则操作执行中批处理的最大消息数。
最小值：2 条消息。最大值：10 条消息
默认值：10 条消息
支持[替换模板](iot-substitution-templates.md)：否
`maxBatchSizeBytes`
消息批处理的最大大小，以字节为单位。
最小值：100 字节。最大值：131,072 字节
默认值：5120 字节
支持[替换模板](iot-substitution-templates.md)：否
**重要**
当您指定多个批处理参数时，批处理将在达到第一个限制时完成。例如，如果您将 100 毫秒指定为最大批处理打开时间，将 5 KiB 指定为最大批处理大小，而规则引擎在 100 毫秒内仅批处理 2 KiB，则将创建并发送 2 KiB 的批处理。
## 批量使用 HTTP 标头
当您在 HTTP 操作中使用标头时，批处理请求会使用最后一条添加到批处理中的消息（不一定是您发布的最后一条消息）中的标头值。我们建议使用以下任一标题值：
+ 批次中的所有消息都相同
+ 适用于所有消息（例如，身份验证凭据）
标头与 HTTP 请求一起发送，不是消息正文的一部分。
**注意**
启用批处理后：
批处理请求会自动包含`Content-Type: application/json`标头，因为批处理是作为 JSON 数组发送的。
我们无法保证批次中的最后一条消息是您发布的最后一条消息。这是进入批次的最后一条消息。
## 有效载荷示例
以下示例显示了发送到您的 HTTP 终端节点的批量消息负载的结构：
```
[
{
"user_id": "user1",
"steps_today": 1000
},
{
"user_id": "user2",
"steps_today": 21000
},
{
"user_id": "user8",
"steps_today": 1500
},
...
]
```
## 限制
以下是批处理的限制：
+ Amazon IoT Core 不能保证消息的整体顺序。批处理是在每台主机上本地执行的，这可能会导致批处理中的消息的顺序与接收顺序不同。
+ Amazon IoT Core 不在接收方提供消息处理支持。您有责任确保将下游服务配置为批量接受和处理数据。
+ 不支持跨账户批处理，即使消息的目的地是相同的资源标识符（HTTP URL 或资源 ARN）。
+ Amazon IoT Core 不能保证批量大小符合您指定的配置。根据时间和消息流，批次可能会小于您配置的限制。
+ 启用批处理后，不支持二进制负载（非 UTF-8 数据）。只接受 UTF-8 文本负载（例如 JSON）。要发送二进制数据，请先对其进行base64编码，然后再将其发送到 HTTP 操作，然后在接收端点对其进行解码。例如，您可以使用物联网规则中的[编码功能](iot-sql-functions.html#iot-function-encode)对二进制有效负载进行编码。或者，您可以对物联网设备中的二进制有效负载进行编码并将其发布到。 Amazon IoT Core
## 批处理的错误操作
您将无法在错误操作定义中定义单独的批处理逻辑。但是，如果您在主操作中定义了批处理逻辑，则您的错误操作将支持批处理。
当批量请求失败时， Amazon IoT Core 规则引擎将遵循 [HTTP 操作重试逻辑](https-rule-action.md#https-rule-action-retry-logic)。在最后一次重试尝试之后，将对整个失败的批次调用错误操作。
以下是启用批处理时出现的错误操作消息的示例：
```
{
"ruleName": "FailedTopicRule",
"topic": "topic/rulesengine",
"payloadsWithMetadata": [
{
"id": 1,
"cloudwatchTraceId": "bebd6d93-6d4a-899e-9e40-56e82252d2be",
"clientId": "Test",
"sourceIp": "10.0.0.0",
"base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
},
{
"id": 2,
"cloudwatchTraceId": "af94d3b8-0b18-1dbf-2c7d-513f5cb9e2e1",
"clientId": "Test",
"sourceIp": "10.0.0.0",
"base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
},
{
"id": 3,
"cloudwatchTraceId": "ca441266-c2ce-c916-6aee-b9e5c7831675",
"clientId": "Test",
"sourceIp": "10.0.0.0",
"base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
}
],
"failures": [
{
"affectedIds": [
1,
2,
3
],
"failedAction": "HttpAction",
"failedResource": "https://example.foobar.com/HttpAction",
"errorMessage": "HttpAction failed to make a request to the specified endpoint. StatusCode: 500. Reason: Internal Server Error."
},
{
"affectedIds": [
3
],
"failedAction": "S3Action",
"failedResource": "amzn-s3-demo-bucket",
"errorMessage": "Failed to put S3 object. The error received was The specified bucket does not exist"
},
{
"affectedIds": [
3
],
"failedAction": "LambdaAction",
"failedResource": "arn:aws:lambda:us-west-2:123456789012:function:dummy",
"errorMessage": "Failed to invoke lambda function. Received Server error from Lambda. The error code is 403"
}
]
}
```
**注意**
批量操作失败还会生成更大的错误操作有效负载，这可能会增加由于大小而导致错误操作失败的概率。您可以使用该`ErrorActionFailure`指标监控错误操作失败。请参阅[规则操作指标](metrics_dimensions.md#rule-action-metrics)了解更多信息。
## 使用批处理 HTTP 操作消息 Amazon CLI
### 使用批处理创建或更新规则操作
1. 使用相应的 Amazon CLI 命令创建或更新规则：
+ 要创建新规则，请使用以下[create-topic-rule](https://docs.amazonaws.cn/cli/latest/reference/iot/create-topic-rule.html)命令：
```
aws iot create-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
+ 要更新现有规则，请使用以下[replace-topic-rule](https://docs.amazonaws.cn/cli/latest/reference/iot/replace-topic-rule.html)命令：
```
aws iot replace-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
1. 通过在主题规则负载中将 enableBatching 参数设置为 true 来启用批处理功能：
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"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}"
}
],
"enableBatching": true,
"batchConfig": {
"maxBatchOpenMs": 100,
"maxBatchSize": 5,
"maxBatchSizeBytes": 1024
}
}
}
]
}
```
1. 配置批处理参数。您无需指定所有批处理参数。您可以选择指定 1、2 或全部 3 个批处理参数。如果您未指定批处理参数，则规则引擎将使用默认值更新该参数。有关批处理参数及其默认值的更多信息，请参阅 [HTTP 参数](https-rule-action.md#https-rule-action-parameters)。
# HTTP 操作目的地
HTTP 操作目标是一项 Web 服务，规则引擎可以将主题规则中的数据路由到该服务。 Amazon IoT Core 资源描述了 Web 服务 Amazon IoT。目标资源可以由不同的规则共享。
在向其他 Web 服务发送数据之前 Amazon IoT Core ，它必须确认自己可以访问该服务的终端节点。
## 概述
HTTP 操作目标指的是支持确认 URL 和一个或多个数据收集的 Web 服务 URLs。目标资源包含您的 Web 服务的确认 URL。配置 HTTP 操作时，需要指定应接收数据的端点的实际 URL 以及 Web 服务的确认 URL。确认目标后，主题规则会将 SQL 语句的结果发送到 HTTPS 端点（而不是发送到确认 URL）。
HTTP 操作目标可以处于以下状态之一：
已启用
已经确认目标，可以由规则操作使用。目标必须处于 `ENABLED` 状态才能在规则中使用。您只能启用处于 DISABLED 状态的目标。
DISABLED
已经确认目标，但规则操作无法使用。如果您希望暂时阻止流入端点的流量而无需再次完成确认流程，则此功能非常有用。您只能禁用处于 ENABLED 状态的目标。
进行中
正在确认目标。
ERROR
目标确认超时。
在确认并启用 HTTP 操作目标后，它可以与您账户中的任何规则一起使用。
## 管理 HTTP 操作目标
您可以使用以下操作来管理您的 HTTP 操作目标。
### 创建 HTTP 操作目标
您可以通过调用`CreateTopicRuleDestination`操作或使用 Amazon IoT 控制台创建 HTTP 操作目标。
创建目标后， Amazon IoT 向确认 URL 发送确认请求。确认请求的格式如下：
```
HTTP POST {confirmationUrl}/?confirmationToken={confirmationToken}
Headers:
x-amz-rules-engine-message-type: DestinationConfirmation
x-amz-rules-engine-destination-arn:"arn:aws:iot:us-east-1:123456789012:ruledestination/http/7a280e37-b9c6-47a2-a751-0703693f46e4"
Content-Type: application/json
Body:
{
"arn":"arn:aws:iot:us-east-1:123456789012:ruledestination/http/7a280e37-b9c6-47a2-a751-0703693f46e4",
"confirmationToken": "AYADeMXLrPrNY2wqJAKsFNn-…NBJndA",
"enableUrl": "https://iot.us-east-1.amazonaws.com/confirmdestination/AYADeMXLrPrNY2wqJAKsFNn-…NBJndA",
"messageType": "DestinationConfirmation"
}
```
确认请求的内容包含以下信息：
arn
要确认的 HTTP 操作目标的亚马逊资源名称 (ARN)。
confirmationToken
发送的确认令牌 Amazon IoT Core。示例中是已截断的令牌。您的令牌会更长。您需要此令牌用 Amazon IoT Core来确认您的目的地。
enableUrl
您需要浏览以确认主题规则目标的 URL。
messageType
消息类型。
### 正在确认 HTTP 操作目的地
要完成端点确认过程，如果您使用 Amazon CLI，则必须在确认 URL 收到确认请求后执行以下步骤。
1.
**确认目标已准备好接收消息**
要确认 HTTP 操作目标已准备好接收物联网消息，请在确认请求`enableUrl`中调用，或者执行 `ConfirmTopicRuleDestination` API 操作并传递确认请求`confirmationToken`中的。
1.
**将主题规则状态设置为已启用**
确认目标可以接收消息后，必须执行 `UpdateTopicRuleDestination` API 操作才能将主题规则的状态设置为 `ENABLED`。
如果您使用的是 Amazon IoT 控制台，请将其复制`confirmationToken`并粘贴到控制 Amazon IoT 台中目标的确认对话框中。然后，您就可以启用主题规则。
### 发送新确认请求
要为目标激活新的确认消息，请调用 `UpdateTopicRuleDestination` 并将主题规则目标的状态设置为 `IN_PROGRESS`。
发送新的确认请求后，重复确认过程。
### 禁用和删除 HTTP 操作目标
要禁用目标，请调用 `UpdateTopicRuleDestination` 并将主题规则目标的状态设置为 `DISABLED`。可以再次启用处于 DISABLED 状态的主题规则，而无需发送新的确认请求。
要删除 HTTP 操作目标，请调用`DeleteTopicRuleDestination`。
## 证书颁发机构 Support
**注意**
不支持自签名证书。
HTTP 操作目标中的 HTTPS 端点支持[Amazon 私有证书颁发机构和 Lets E [ncrypt](https://letsencrypt.org/certificates/) 颁发的证书](https://www.amazontrust.com/repository/)。
# Amazon IoT Events
Amazon IoT Events (`iotEvents`) 操作将数据从 MQTT 消息发送到 Amazon IoT Events 输入。
**重要**
如果将有效负载发送到时 Amazon IoT Core 不带有`Input attribute Key`，或者密钥不在密钥中指定的 JSON 路径中，则会导致物联网规则失败并出现错误`Failed to send message to Iot Events`。
## 要求
此规则操作具有以下要求：
+ Amazon IoT 可以代入执行`iotevents:BatchPutMessage`操作的 IAM 角色。有关更多信息，请参阅 [授予 Amazon IoT 规则所需的访问权限](iot-create-role.md)。
在 Amazon IoT 控制台中，您可以选择或创建 Amazon IoT 允许执行此规则操作的角色。
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
`batchMode`
（可选）是否批处理事件操作。默认值为 `false`。
当`batchMode`为`true`且规则 SQL 语句的计算结果为数组时，通过调用[https://docs.amazonaws.cn/iotevents/latest/apireference/API_iotevents-data_BatchPutMessage.html](https://docs.amazonaws.cn/iotevents/latest/apireference/API_iotevents-data_BatchPutMessage.html)将每个数组元素发送到 Ev Amazon IoT ents 时，每个数组元素都被视为一条单独的消息。生成的数组，其消息不得超过 10 条。
`batchMode` 为 `true` 时，不能指定 `messageId`。
支持[替换模板](iot-substitution-templates.md)：否
`inputName`
Amazon IoT Events 输入的名称。
仅支持[替换模板](iot-substitution-templates.md)：API 且 Amazon CLI 仅支持
`messageId`
（可选）使用它来验证 Amazon IoT Events 检测器`messageId`是否只处理一个给定输入（消息）。您可以使用 `${newuuid()}` 替代模板，以便为每个请求生成一个唯一的 ID。
当 `batchMode` 为 `true` 时，您无法指定 `messageId`，将分配一个新 UUID 值。
支持[替换模板](iot-substitution-templates.md)：是
`roleArn`
允许 Amazon IoT 向 Amazon IoT Events 检测器发送输入的 IAM 角色。有关更多信息，请参阅 [要求](#iotevents-rule-action-requirements)。
支持[替换模板](iot-substitution-templates.md)：否
## 示例
下面的 JSON 示例介绍了如何在 Amazon IoT 规则中定义物联网Events 操作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"iotEvents": {
"inputName": "MyIoTEventsInput",
"messageId": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_events"
}
}
]
}
}
```
## 另请参阅
+ [什么是 Amazon IoT Events？](https://docs.amazonaws.cn/iotevents/latest/developerguide/) 在《*Amazon IoT Events 开发者指南》*中
# Amazon IoT SiteWise
Amazon IoT SiteWise (`iotSiteWise`) 操作将数据从 MQTT 消息发送到中的资产属性。 Amazon IoT SiteWise
你可以遵循一个教程，向你展示如何从 Amazon IoT 事物中提取数据。*有关更多信息，请参阅《用户指南》[中的 “ Amazon IoT SiteWise 从 Amazon IoT 事物中提取数据](https://docs.amazonaws.cn/iot-sitewise/latest/userguide/ingest-data-from-iot-things.html)[” 教程或 “使用 Amazon IoT 核心规则提取数据](https://docs.amazonaws.cn/iot-sitewise/latest/userguide/iot-rules.html)” 部分。Amazon IoT SiteWise *
## 要求
此规则操作具有以下要求：
+ Amazon IoT 可以代入执行`iotsitewise:BatchPutAssetPropertyValue`操作的 IAM 角色。有关更多信息，请参阅 [授予 Amazon IoT 规则所需的访问权限](iot-create-role.md)。
您可以将下列示例信任策略附加到要代入的角色。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*"
}
]
}
```
为了提高安全性，您可以在`Condition`属性中指定 Amazon IoT SiteWise 资产层次结构路径。以下示例是指定资产层次结构路径的信任策略。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*",
"Condition": {
"StringLike": {
"iotsitewise:assetHierarchyPath": [
"/root node asset ID",
"/root node asset ID/*"
]
}
}
}
]
}
```
+ 当您通过此操作向发送数据时，您的数据必须满足`BatchPutAssetPropertyValue`操作的要求。 Amazon IoT SiteWise 有关更多信息，请参阅《Amazon IoT SiteWise API Reference》**中的 [BatchPutAssetPropertyValue](https://docs.amazonaws.cn/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html)。
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
`putAssetPropertyValueEntries`
包含以下信息的资产属性值条目的列表：
`propertyAlias`
（可选）与您的资产属性关联的属性别名。指定 `propertyAlias` 或同时指定 `assetId` 和 `propertyId`。有关更多信息，请参阅 *《Amazon IoT SiteWise 用户指南》*中的[将工业数据流映射到资产属性](https://docs.amazonaws.cn/iot-sitewise/latest/userguide/connect-data-streams.html)。
支持[替换模板](iot-substitution-templates.md)：是
`assetId`
（可选） Amazon IoT SiteWise 资产的 ID。指定 `propertyAlias` 或同时指定 `assetId` 和 `propertyId`。
支持[替换模板](iot-substitution-templates.md)：是
`propertyId`
（可选）资产属性的 ID。指定 `propertyAlias` 或同时指定 `assetId` 和 `propertyId`。
支持[替换模板](iot-substitution-templates.md)：是
`entryId`
（可选）此条目的唯一标识符。定义 `entryId`，以便在出现故障时更好地跟踪哪条消息导致了错误。默认为新 UUID。
支持[替换模板](iot-substitution-templates.md)：是
`propertyValues`
要插入的属性值的列表，均包含以下格式的时间戳、质量和值（TQV）：
`timestamp`
包含以下信息的时间戳结构：
`timeInSeconds`
包含用 Unix 纪元时间表示的时间（以秒为单位）的字符串。如果您的消息负载没有时间戳，则可使用 [timestamp()](iot-sql-functions.md#iot-function-timestamp)，它将返回当前时间（以毫秒为单位）。要将该时间转换为秒，可以使用以下替换模板：**\$1\$1floor(timestamp() / 1E3)\$1**。
支持[替换模板](iot-substitution-templates.md)：是
`offsetInNanos`
（可选）包含与以秒为单位的时间的纳秒时间偏移量的字符串。如果您的消息负载没有时间戳，则可使用 [timestamp()](iot-sql-functions.md#iot-function-timestamp)，它将返回当前时间（以毫秒为单位）。要计算与该时间的纳秒偏移量，可以使用以下替换模板：**\$1\$1(timestamp() % 1E3) \$1 1E6\$1**。
支持[替换模板](iot-substitution-templates.md)：是
关于 Unix 纪元时间，仅 Amazon IoT SiteWise 接受时间戳最长为过去 7 天、将来最多 5 分钟的条目。
`quality`
（可选）描述值的质量的字符串。有效值：`GOOD`、`BAD`、`UNCERTAIN`。
支持[替换模板](iot-substitution-templates.md)：是
`value`
包含以下值字段之一的值结构，具体取决于资产属性的数据类型：
`booleanValue`
（可选）包含值条目布尔值的字符串。
支持[替换模板](iot-substitution-templates.md)：是
`doubleValue`
（可选）包含值条目的双值的字符串。
支持[替换模板](iot-substitution-templates.md)：是
`integerValue`
（可选）包含值条目整数值的字符串。
支持[替换模板](iot-substitution-templates.md)：是
`stringValue`
（可选）值条目的字符串值。
支持[替换模板](iot-substitution-templates.md)：是
`roleArn`
授予向发送资产属性值的 Amazon IoT 权限的 IAM 角色的 ARN。 Amazon IoT SiteWise有关更多信息，请参阅 [要求](#iotsitewise-rule-action-requirements)。
支持[替换模板](iot-substitution-templates.md)：否
## 示例
以下 JSON 示例在 Amazon IoT 规则中定义了基本的 IoT SiteWise 操作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"iotSiteWise": {
"putAssetPropertyValueEntries": [
{
"propertyAlias": "/some/property/alias",
"propertyValues": [
{
"timestamp": {
"timeInSeconds": "${my.payload.timeInSeconds}"
},
"value": {
"integerValue": "${my.payload.value}"
}
}
]
}
],
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sitewise"
}
}
]
}
}
```
以下 JSON 示例在 Amazon IoT 规则中定义了物联网 SiteWise 操作。此示例将主题用作属性别名和 `timestamp()` 函数。例如，如果您将数据发布到 `/company/windfarm/3/turbine/7/rpm`，则此操作会将数据发送到具有与您指定的主题相同的属性别名的资产属性。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM '/company/windfarm/+/turbine/+/+'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"iotSiteWise": {
"putAssetPropertyValueEntries": [
{
"propertyAlias": "${topic()}",
"propertyValues": [
{
"timestamp": {
"timeInSeconds": "${floor(timestamp() / 1E3)}",
"offsetInNanos": "${(timestamp() % 1E3) * 1E6}"
},
"value": {
"doubleValue": "${my.payload.value}"
}
}
]
}
],
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sitewise"
}
}
]
}
}
```
## 另请参阅
+ *Amazon IoT SiteWise 用户指南* 中的[什么是 Amazon IoT SiteWise？](https://docs.amazonaws.cn/iot-sitewise/latest/userguide/what-is-sitewise.html)
+ [https://docs.amazonaws.cn/iot-sitewise/latest/userguide/iot-rules.html](https://docs.amazonaws.cn/iot-sitewise/latest/userguide/iot-rules.html)
+ [Amazon IoT SiteWise*从《用户指南》中的 Amazon IoT 事物中Amazon IoT SiteWise 提取数据*](https://docs.amazonaws.cn/iot-sitewise/latest/userguide/ingest-data-from-iot-things.html)
+ *Amazon IoT SiteWise 用户指南*[中的 Amazon IoT SiteWise 规则操作疑难解答](https://docs.amazonaws.cn/iot-sitewise/latest/userguide/troubleshoot-rule.html)
# Firehose
Firehose (`firehose`) 操作可将 MQTT 消息中的数据发送至 Amazon Data Firehose 流。
## 要求
此规则操作具有以下要求：
+ Amazon IoT 可以代入执行`firehose:PutRecord`操作的 IAM 角色。有关更多信息，请参阅 [授予 Amazon IoT 规则所需的访问权限](iot-create-role.md)。
在 Amazon IoT 控制台中，您可以选择或创建 Amazon IoT 允许执行此规则操作的角色。
+ 如果您使用 Firehose 将数据发送到亚马逊 S3 存储桶，并且您使用托管 Amazon KMS Amazon KMS key 客户加密亚马逊 S3 中的静态数据，则 Firehose 必须有权访问您的存储桶，并有权 Amazon KMS key 代表调用者使用这些存储桶。有关更多信息，请参阅《Amazon Data Firehose 开发人员指南》**中的 [Grant Firehose access to an Amazon S3 destination](https://docs.amazonaws.cn/firehose/latest/dev/controlling-access.html#using-iam-s3)。
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
`batchMode`
（可选）通过使用 [https://docs.amazonaws.cn/firehose/latest/APIReference/API_PutRecordBatch.html](https://docs.amazonaws.cn/firehose/latest/APIReference/API_PutRecordBatch.html) 批量交付 Firehose 流。默认值为 `false`。
当 `batchMode` 为 `true` 且规则的 SQL 语句求值为一个数组时，每个数组元素在 `PutRecordBatch` 请求中形成一条记录。生成的数组，其记录不得超过 500 条。
支持[替换模板](iot-substitution-templates.md)：否
`deliveryStreamName`
消息数据写入的 Firehose 流。
仅支持[替换模板](iot-substitution-templates.md)：API 且 Amazon CLI 仅支持
`separator`
（可选）将用于分隔写入 Firehose 流的记录的分隔符。如果省略此参数，则流不使用分隔符。有效值：`,`（逗号），`\t`（选项卡），`\n`（换行符），`\r\n`（窗口换行符）。
支持[替换模板](iot-substitution-templates.md)：否
`roleArn`
授予对 Firehose 流的访问权限的 IAM 角色。有关更多信息，请参阅 [要求](#kinesis-firehose-rule-action-requirements)。
支持[替换模板](iot-substitution-templates.md)：否
## 示例
以下 JSON 示例在规则中定义了 Fireh Amazon IoT ose 操作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"firehose": {
"deliveryStreamName": "my_firehose_stream",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_firehose"
}
}
]
}
}
```
以下 JSON 示例使用规则中的替换模板定义了 Firehose Amazon IoT 操作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"firehose": {
"deliveryStreamName": "${topic()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_firehose"
}
}
]
}
}
```
## 另请参阅
+ *《Amazon Data Firehose 开发人员指南》*中的 [What is Amazon Data Firehose?](https://docs.amazonaws.cn/firehose/latest/dev/)
# Kinesis Data Streams
Kinesis Data Streams (`kinesis`) 操作将 MQTT 消息中的数据写入 Amazon Kinesis Data Streams。
## 要求
此规则操作具有以下要求：
+ Amazon IoT 可以代入执行`kinesis:PutRecord`操作的 IAM 角色。有关更多信息，请参阅 [授予 Amazon IoT 规则所需的访问权限](iot-create-role.md)。
在 Amazon IoT 控制台中，您可以选择或创建 Amazon IoT 允许执行此规则操作的角色。
+ 如果您使用 Amazon KMS 客户管理的 Amazon KMS key （KMS 密钥）对 Kinesis Data Streams 中的静态数据进行加密，则该服务必须有权代表调用方使用 Amazon KMS key 。有关更多信息，请参阅*《Amazon Kinesis Data Streams 开发人员指南》*中的[使用用户生成的 Amazon KMS keys的权限](https://docs.amazonaws.cn/streams/latest/dev/permissions-user-key-KMS.html)。
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
`stream`
数据写入的 Kinesis 数据流。
仅支持[替换模板](iot-substitution-templates.md)：API 且 Amazon CLI 仅支持
`partitionKey`
用于确定将数据写入哪个分区的分区键。分区键通常由表达式（例如，`${topic()}` 或 `${timestamp()}`）组成。
支持[替换模板](iot-substitution-templates.md)：是
`roleArn`
授予访问 Kinesis 数据流 Amazon IoT 权限的 IAM 角色的 ARN。有关更多信息，请参阅 [要求](#kinesis-rule-action-requirements)。
支持[替换模板](iot-substitution-templates.md)：否
## 示例
以下 JSON 示例在规则中定义了 Kinesis Data Streams 操作 Amazon IoT 。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"kinesis": {
"streamName": "my_kinesis_stream",
"partitionKey": "${topic()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_kinesis"
}
}
]
}
}
```
以下 JSON 示例使用规则中的替换模板定义了 Kinesis 操作。 Amazon IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"kinesis": {
"streamName": "${topic()}",
"partitionKey": "${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_kinesis"
}
}
]
}
}
```
## 另请参阅
+ *Amazon Kinesis Data Streams 开发人员指南*中的[什么是 Amazon Kinesis Data Streams？](https://docs.amazonaws.cn/streams/latest/dev/)
# Lambda
Lambda (`lambda`) 操作调用一个 Amazon Lambda 函数，传入 MQTT 消息。 Amazon IoT 异步调用 Lambda 函数。
您可以按照教程执行操作，该教程向您说明如何使用 Lambda 操作创建并测试规则。有关更多信息，请参阅 [教程：使用 Amazon Lambda 函数格式化通知](iot-lambda-rule.md)。
## 要求
此规则操作具有以下要求：
+ Amazon IoT 要调用 Lambda 函数，必须配置授予`lambda:InvokeFunction`权限的策略。 Amazon IoT您只能调用 Lambda 策略 Amazon Web Services 区域 所在位置定义的 Lambda 函数。Lambda 函数使用基于资源的策略，因此您必须将该策略附加到 Lambda 函数本身。
使用以下 Amazon CLI 命令附加授予`lambda:InvokeFunction`权限的策略。在该命令中，将：
+ *function\$1name*使用 Lambda 函数的名称。添加新的权限来更新函数的资源策略。
+ *region*使用函数 Amazon Web Services 区域 的。
+ *account-id*使用定义规则的 Amazon Web Services 账户 数字。
+ *rule-name*使用您要为其定义 Lambda 操作的 Amazon IoT 规则的名称。
+ *unique\$1id*带有唯一的语句标识符。
**重要**
如果您在不提供`source-arn`或的情况下为 Amazon IoT 委托人添加权限`source-account`，则任何 Amazon Web Services 账户 使用您的 Lambda 操作创建规则的人都可以激活规则，从中调用您的 Lambda 函数。 Amazon IoT
有关更多信息，请参阅 [Amazon Lambda 权限](https://docs.amazonaws.cn/lambda/latest/dg/intro-permission-model.html)。
```
aws lambda add-permission \
--function-name function_name \
--region region \
--principal iot.amazonaws.com \
--source-arn arn:aws:iot:region:account-id:rule/rule_name \
--source-account account-id
--statement-id unique_id
--action "lambda:InvokeFunction"
```
+ 如果您使用 Amazon IoT 控制台为 Lambda 规则操作创建规则，则会自动触发 Lambda 函数。如果 Amazon CloudFormation 改用 [https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/aws-properties-iot-topicrule-lambdaaction.html](https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/aws-properties-iot-topicrule-lambdaaction.html)，则必须添加[https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-permission.html](https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-permission.html)资源。然后该资源授予您触发 Lambda 函数的权限。
以下代码显示了如何添加此资源的示例。在此示例中：
+ *function\$1name*使用 Lambda 函数的名称。
+ *region*使用函数 Amazon Web Services 区域 的。
+ *account-id*使用定义规则的 Amazon Web Services 账户 数字。
+ *rule-name*使用您要为其定义 Lambda 操作的 Amazon IoT 规则的名称。
```
Type: AWS::Lambda::Permission
Properties:
Action: lambda:InvokeFunction
FunctionName: !Ref function_name
Principal: "iot.amazonaws.com"
SourceAccount: account-id
SourceArn: arn:aws:iot:region:account-id:rule/rule_name
```
+ 如果您使用 Amazon KMS 客户托管 Amazon KMS key 对 Lambda 中的静态数据进行加密，则该服务必须有权代表调用者使用这些数据。 Amazon KMS key 有关更多信息，请参阅*《Amazon Lambda 开发人员指南》*中的[静态加密](https://docs.amazonaws.cn/lambda/latest/dg/security-dataprotection.html#security-privacy-atrest)。
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
`functionArn`
要调用的 Lambda 函数的 ARN。 Amazon IoT 必须具有调用该函数的权限。有关更多信息，请参阅 [要求](#lambda-rule-action-requirements)。
如果您未指定 Lambda 函数的版本或别名，则将关闭该函数的最新版本。如果要关闭 Lambda 函数的特定版本，则可指定版本或别名。要指定一个版本或别名，请将该版本或别名附加到 Lambda 函数的 ARN。
```
arn:aws:lambda:us-east-2:123456789012:function:myLambdaFunction:someAlias
```
有关版本控制和别名的更多信息，请参阅 [Amazon Lambda 函数版本控制和别名](https://docs.amazonaws.cn/lambda/latest/dg/versioning-aliases.html)。
仅支持[替换模板](iot-substitution-templates.md)：API 且 Amazon CLI 仅支持
## 示例
以下 JSON 示例在规则中定义了 Lambda 操作。 Amazon IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-east-2:123456789012:function:myLambdaFunction"
}
}
]
}
}
```
以下 JSON 示例定义了在规则中使用替换模板的 Lambda 操作。 Amazon IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-east-1:123456789012:function:${topic()}"
}
}
]
}
}
```
## 另请参阅
+ [什么是 Amazon Lambda？](https://docs.amazonaws.cn/lambda/latest/dg/) 在《*Amazon Lambda 开发者指南》*中
+ [教程：使用 Amazon Lambda 函数格式化通知](iot-lambda-rule.md)
# 位置
Location (`location`) 操作会将您的地理位置数据路由到 [Amazon Location Service](https://docs.amazonaws.cn//location/latest/developerguide/welcome.html)。
**注意**
此操作在中国不可用。
## 要求
此规则操作具有以下要求：
+ Amazon IoT 可以代入执行`geo:BatchUpdateDevicePosition`操作的 IAM 角色。有关更多信息，请参阅 [授予 Amazon IoT 规则所需的访问权限](iot-create-role.md)。
在 Amazon IoT 控制台中，您可以选择或创建 Amazon IoT 允许执行此规则操作的角色。
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
`deviceId`
提供位置数据的设备的唯一 ID。有关更多信息，请参阅《Amazon Location Service API 参考》** 中的 [https://docs.amazonaws.cn//location/latest/APIReference/API_DevicePositionUpdate.html](https://docs.amazonaws.cn//location/latest/APIReference/API_DevicePositionUpdate.html)。
支持[替换模板](iot-substitution-templates.md)：是
`latitude`
计算结果为表示设备位置纬度的双精度值的字符串。
支持[替换模板](iot-substitution-templates.md)：是
`longitude`
计算结果为表示设备位置经度的双精度值的字符串。
支持[替换模板](iot-substitution-templates.md)：是
`roleArn`
允许访问 Amazon Location Service 域的 IAM 角色。有关更多信息，请参阅 [要求](#location-rule-action-requirements)。
`timestamp`
对位置数据进行采样的时间。默认值是处理 MQTT 消息的时间。
`timestamp` 值由以下两个值组成：
+ `value`：返回长纪元时间值的表达式。您可以使用 [time\$1to\$1epoch(String, String)](iot-sql-functions.md#iot-sql-function-time-to-epoch) 函数从消息负载中传递的日期或时间值创建有效的时间戳。支持[替换模板](iot-substitution-templates.md)：是。
+ `unit`：（可选）`value` 中描述的表达式生成的时间戳值的精度。有效值：`SECONDS` \$1 `MILLISECONDS` \$1`MICROSECONDS` \$1 `NANOSECONDS`。默认值为 `MILLISECONDS`。仅支持[替换模板](iot-substitution-templates.md)：API 且 Amazon CLI 仅支持。
`trackerName`
Amazon Location 中更新位置的跟踪器资源的名称。有关更多信息，请参阅*《Amazon Location Service 开发人员指南》* 中的[跟踪器](https://docs.amazonaws.cn//location/latest/developerguide/geofence-tracker-concepts.html#tracking-overview)。
仅支持[替换模板](iot-substitution-templates.md)：API 且 Amazon CLI 仅支持
## 示例
以下 JSON 示例在 Amazon IoT 规则中定义了定位操作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"location": {
"roleArn": "arn:aws:iam::123454962127:role/service-role/ExampleRole",
"trackerName": "MyTracker",
"deviceId": "001",
"sampleTime": {
"value": "${timestamp()}",
"unit": "MILLISECONDS"
},
"latitude": "-12.3456",
"longitude": "65.4321"
}
}
]
}
}
```
以下 JSON 示例定义了在 Amazon IoT 规则中使用替换模板的定位操作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"location": {
"roleArn": "arn:aws:iam::123456789012:role/service-role/ExampleRole",
"trackerName": "${TrackerName}",
"deviceId": "${DeviceID}",
"timestamp": {
"value": "${timestamp()}",
"unit": "MILLISECONDS"
},
"latitude": "${get(position, 0)}",
"longitude": "${get(position, 1)}"
}
}
]
}
}
```
以下 MQTT 有效载荷示例显示了上面示例中的替换模板如何访问数据。您可以使用 [https://docs.amazonaws.cn/cli/latest/reference/location/get-device-position-history.html](https://docs.amazonaws.cn/cli/latest/reference/location/get-device-position-history.html) CLI 命令来验证 MQTT 有效载荷数据是否已在位置跟踪器中传递。
```
{
"TrackerName": "mytracker",
"DeviceID": "001",
"position": [
"-12.3456",
"65.4321"
]
}
```
```
aws location get-device-position-history --device-id 001 --tracker-name mytracker
```
```
{
"DevicePositions": [
{
"DeviceId": "001",
"Position": [
-12.3456,
65.4321
],
"ReceivedTime": "2022-11-11T01:31:54.464000+00:00",
"SampleTime": "2022-11-11T01:31:54.308000+00:00"
}
]
}
```
## 另请参阅
+ [《Amazon Location Service 开发人员指南》](https://docs.amazonaws.cn//location/latest/developerguide/welcome.html) 中的*什么是 Amazon Location Service？*。
# OpenSearch
OpenSearch (`openSearch`) 操作将来自 MQTT 消息的数据写入亚马逊 OpenSearch 服务域。然后，您可以使用 OpenSearch 仪表板等工具在 Ser OpenSearch vice 中查询和可视化数据。
## 要求
此规则操作具有以下要求：
+ Amazon IoT 可以代入执行`es:ESHttpPut`操作的 IAM 角色。有关更多信息，请参阅 [授予 Amazon IoT 规则所需的访问权限](iot-create-role.md)。
在 Amazon IoT 控制台中，您可以选择或创建 Amazon IoT 允许执行此规则操作的角色。
+ 如果您使用客户管理 Amazon KMS key 来加密 OpenSearch 服务中的静态数据，则该服务必须有权代表呼叫者使用 KMS 密钥。有关更多信息，请参阅[《亚马逊服务*开发者指南》*中的亚马逊 OpenSearch 服务静态数据加密](https://docs.amazonaws.cn/opensearch-service/latest/developerguide/encryption-at-rest.html)。 OpenSearch
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
`endpoint`
您的亚马逊 OpenSearch 服务域的终端节点。
仅支持[替换模板](iot-substitution-templates.md)：API 且 Amazon CLI 仅支持
`index`
您要存储数据的 OpenSearch 索引。
支持[替换模板](iot-substitution-templates.md)：是
`type`
您存储的文档类型。
对于高于 1.0 的 OpenSearch 版本，`type`参数的值必须为`_doc`。有关详情，请参阅 [OpenSearch 文档](https://opensearch.org/docs/1.0/opensearch/rest-api/document-apis/index-document/#response-body-fields)。
支持[替换模板](iot-substitution-templates.md)：是
`id`
每个文档的唯一标识符。
支持[替换模板](iot-substitution-templates.md)：是
`roleARN`
允许访问 OpenSearch 服务域的 IAM 角色。有关更多信息，请参阅 [要求](#opensearch-rule-action-requirements)。
支持[替换模板](iot-substitution-templates.md)：否
## 限制
OpenSearch (`openSearch`) 操作不能用于向 VPC Elasticsearch 集群传输数据。
## 示例
以下 JSON 示例定义了 Amazon IoT 规则中的 OpenSearch 操作以及如何为该`OpenSearch`操作指定字段。有关更多信息，请参阅 [OpenSearchAction](https://docs.amazonaws.cn/iot/latest/apireference/API_OpenSearchAction.html)。
```
{
"topicRulePayload": {
"sql": "SELECT *, timestamp() as timestamp FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"openSearch": {
"endpoint": "https://my-endpoint",
"index": "my-index",
"type": "_doc",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_os"
}
}
]
}
}
```
以下 JSON 示例定义了一个在 Amazon IoT 规则中使用替换模板的 OpenSearch 操作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"openSearch": {
"endpoint": "https://my-endpoint",
"index": "${topic()}",
"type": "${type}",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_os"
}
}
]
}
}
```
**注意**
替换的`type`字段适用于 OpenSearch 版本 1.0。对于任何高于 1.0 的版本，`type` 的值必须为 `_doc`。
## 另请参阅
[什么是亚马逊 OpenSearch 服务？](https://docs.amazonaws.cn/opensearch-service/latest/developerguide/) 在《*亚马逊 OpenSearch 服务开发者指南》*中
# 重新发布
重新发布 (`republish`) 操作可将 MQTT 消息重新发布到其它 MQTT 主题。
## 要求
此规则操作具有以下要求：
+ Amazon IoT 可以代入执行`iot:Publish`操作的 IAM 角色。有关更多信息，请参阅 [授予 Amazon IoT 规则所需的访问权限](iot-create-role.md)。
在 Amazon IoT 控制台中，您可以选择或创建 Amazon IoT 允许执行此规则操作的角色。
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
`headers`
MQTT 版本 5.0 标头信息。
有关更多信息，请参阅《*Amazon API 参考*》中的[RepublishAction](https://docs.amazonaws.cn//iot/latest/apireference/API_RepublishAction.html)和[MqttHeaders](https://docs.amazonaws.cn//iot/latest/apireference/API_MqttHeaders.html)。
`topic`
消息重新发布到的 MQTT 主题。
若要重新发布到以 `$` 开头的预留主题，请使用 `$$` 代替。例如，如果要重新发布到设备影子主题 `$aws/things/MyThing/shadow/update`，请将主题指定为 `$$aws/things/MyThing/shadow/update`。
不支持重新发布到[保留的任务主题](reserved-topics.md#reserved-topics-job)。
Amazon IoT Device Defender 保留主题不支持 HTTP 发布。
支持[替换模板](iot-substitution-templates.md)：是
`qos`
（可选）重新发布消息时要使用的服务质量（QoS）级别。有效值：`0`、`1`。默认值为 `0`。有关 MQTT QoS 的更多信息，请参阅 [MQTT](mqtt.md)。
支持[替换模板](iot-substitution-templates.md)：否
`roleArn`
允许发布 Amazon IoT 到 MQTT 主题的 IAM 角色。有关更多信息，请参阅 [要求](#republish-rule-action-requirements)。
支持[替换模板](iot-substitution-templates.md)：否
## 示例
以下 JSON 示例在 Amazon IoT 规则中定义了重新发布操作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "another/topic",
"qos": 1,
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish"
}
}
]
}
}
```
以下 JSON 示例定义了在 Amazon IoT 规则中使用替换模板的重新发布操作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "${topic()}/republish",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish"
}
}
]
}
}
```
以下 JSON 示例在 Amazon IoT 规则`headers`中定义了重新发布操作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "${topic()}/republish",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish",
"headers": {
"payloadFormatIndicator": "UTF8_DATA",
"contentType": "rule/contentType",
"correlationData": "cnVsZSBjb3JyZWxhdGlvbiBkYXRh",
"userProperties": [
{
"key": "ruleKey1",
"value": "ruleValue1"
},
{
"key": "ruleKey2",
"value": "ruleValue2"
}
]
}
}
}
]
}
}
```
**注意**
不会通过[重新发布操作](#republish-rule-action)传递原始源 IP。
# S3
S3 (`s3`) 操作将 MQTT 消息中的数据写入 Amazon Simple Storage Service（Amazon S3）存储桶。
## 要求
此规则操作具有以下要求：
+ Amazon IoT 可以代入执行`s3:PutObject`操作的 IAM 角色。有关更多信息，请参阅 [授予 Amazon IoT 规则所需的访问权限](iot-create-role.md)。
在 Amazon IoT 控制台中，您可以选择或创建 Amazon IoT 允许执行此规则操作的角色。
+ 如果您使用 Amazon KMS 客户托管 Amazon KMS key 来加密Amazon S3中的静态数据，则该服务必须有权代表呼叫者使用这些数据。 Amazon KMS key 有关更多信息，请参阅《*Amazon 简单存储服务开发者指南*》 Amazon KMS keys中的[托Amazon 管 Amazon KMS keys 和客户托管](https://docs.amazonaws.cn/AmazonS3/latest/userguide/UsingKMSEncryption.html#aws-managed-customer-managed-cmks)。
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
`bucket`
数据写入的 Amazon S3 存储桶。
仅支持[替换模板](iot-substitution-templates.md)：API 且 Amazon CLI 仅支持
`cannedacl`
（可选）Amazon S3 封装的 ACL，用于控制对由对象键标识的对象的访问权限。有关更多信息，包括允许的值，请参阅 [封装 ACL](https://docs.amazonaws.cn/AmazonS3/latest/userguide/acl-overview.html#canned-acl)。
支持[替换模板](iot-substitution-templates.md)：否
`key`
数据写入的文件路径。
考虑一个例子，其中此参数是 `${topic()}/${timestamp()}`，并且规则会收到一条消息，其中主题为 `some/topic`。如果当前时间戳为 `1460685389`，那么这个操作会将数据写入一个 S3 存储桶中名为 `some/topic` 的文件夹中的文件 `1460685389`。
如果您使用静态密钥，则每次调用规则时都会 Amazon IoT 覆盖单个文件。我们建议您使用消息时间戳或其它唯一的消息标识符，这样可以在 Amazon S3 中针对接收的每个消息保存一个新文件。
支持[替换模板](iot-substitution-templates.md)：是
`roleArn`
允许访问 Amazon S3 存储桶的 IAM 角色。有关更多信息，请参阅 [要求](#s3-rule-action-requirements)。
支持[替换模板](iot-substitution-templates.md)：否
## 示例
以下 JSON 示例在 Amazon IoT 规则中定义了 S3 操作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"s3": {
"bucketName": "amzn-s3-demo-bucket",
"cannedacl": "public-read",
"key": "${topic()}/${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3"
}
}
]
}
}
```
## 另请参阅
+ *《Amazon Simple Storage Service 用户指南》*中的[什么是 Amazon S3？](https://docs.amazonaws.cn/AmazonS3/latest/userguide/)
# Salesforce 物联
Salesforce物联网(`salesforce`) 操作将来自触发了规则的 MQTT 消息数据发送到 Salesforce物联网输入流。
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
`url`
由 Salesforce物联网输入流公开的 URL。在创建输入流时，可从 Salesforce物联网平台获得该 URL。有关更多信息，请参阅 Salesforce IoT 文档。
支持[替换模板](iot-substitution-templates.md)：否
`token`
用于验证对指定的 Salesforce物联网输入流的访问的令牌。在创建输入流时，可从 Salesforce物联网平台获得该令牌。有关更多信息，请参阅 Salesforce IoT 文档。
支持[替换模板](iot-substitution-templates.md)：否
## 示例
以下 JSON 示例定义了 Amazon IoT 规则中的 Salesforce物联网操作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"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"
}
}
]
}
}
```
# SNS
SNS (`sns`) 操作将 MQTT 消息中的数据作为 Amazon Simple Notification Service（Amazon SNS）推送通知发送。
您可以按照教程执行操作，该教程向您说明如何使用 SNS 操作创建和测试规则。有关更多信息，请参阅 [教程：发送 Amazon SNS 通知](iot-sns-rule.md)。
**注意**
SNS 操作不支持[Amazon SNS FIFO（先进先出）主题](https://docs.amazonaws.cn/sns/latest/dg/sns-fifo-topics.html)。由于规则引擎是一个完全分布式服务，因此无法保证触发 SNS 操作时的消息顺序。
## 要求
此规则操作具有以下要求：
+ Amazon IoT 可以代入执行`sns:Publish`操作的 IAM 角色。有关更多信息，请参阅 [授予 Amazon IoT 规则所需的访问权限](iot-create-role.md)。
在 Amazon IoT 控制台中，您可以选择或创建 Amazon IoT 允许执行此规则操作的角色。
+ 如果您使用 Amazon KMS 客户托管 Amazon KMS key 来加密 Amazon SNS 中的静态数据，则该服务必须有权代表呼叫 Amazon KMS key 者使用这些数据。有关更多信息，请参阅*《Amazon Simple Notification Service 开发人员指南》*中的[密钥管理](https://docs.amazonaws.cn/sns/latest/dg/sns-key-management.html)。
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
`targetArn`
推送通知将发送到的 SNS 主题或单个设备。
仅支持[替换模板](iot-substitution-templates.md)：API 且 Amazon CLI 仅支持
`messageFormat`
（可选）消息格式。Amazon SNS 使用此设置来确定是否应解析有效载荷，以及是否应提取有效载荷的特定于平台的相关部分。有效值：`JSON`、`RAW`。默认值为 `RAW`。
支持[替换模板](iot-substitution-templates.md)：否
`roleArn`
允许访问 SNS 的 IAM 角色。有关更多信息，请参阅 [要求](#sns-rule-action-requirements)。
支持[替换模板](iot-substitution-templates.md)：否
## 示例
以下 JSON 示例在 Amazon 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"
}
}
]
}
}
```
以下 JSON 示例在 Amazon IoT 规则中定义了带有替换模板的 SNS 操作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:us-east-1:123456789012:${topic()}",
"messageFormat": "JSON",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sns"
}
}
]
}
}
```
## 另请参阅
+ *《Amazon Simple Notification Service 开发人员指南》*中的[什么是 Amazon Simple Notification Service？](https://docs.amazonaws.cn/sns/latest/dg/)
+ [教程：发送 Amazon SNS 通知](iot-sns-rule.md)
# SQS
SQS (`sqs`) 操作将 MQTT 消息中的数据发送到 Amazon Simple Queue Service（Amazon SQS）队列。
**注意**
SQS 操作不支持 [Amazon SQS FIFO（先进先出）队列](https://docs.amazonaws.cn/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues.html)。由于规则引擎是一个完全分布式服务，因此无法保证触发 SQS 操作时的消息顺序。
## 要求
此规则操作具有以下要求：
+ Amazon IoT 可以代入执行`sqs:SendMessage`操作的 IAM 角色。有关更多信息，请参阅 [授予 Amazon IoT 规则所需的访问权限](iot-create-role.md)。
在 Amazon IoT 控制台中，您可以选择或创建 Amazon IoT 允许执行此规则操作的角色。
+ 如果您使用 Amazon KMS 客户托管 Amazon KMS key 对 Amazon SQS 中的静态数据进行加密，则该服务必须有权代表来电者使用这些数据。 Amazon KMS key 有关更多信息，请参阅*《Amazon Simple Queue Service 开发人员指南》*中的[密钥管理](https://docs.amazonaws.cn/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-key-management.html)。
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
`queueUrl`
数据写入的 Amazon SQS 队列的 URL。此 URL 中的区域不必与您的[Amazon IoT 规则 Amazon Web Services 区域](https://docs.amazonaws.cn/iot/latest/developerguide/iot-rules.html)相同。
使用 SQS 规则操作跨 Amazon Web Services 区域 进行数据传输可能会产生额外费用。有关更多信息，请参阅 [Amazon SQS 定价](https://www.amazonaws.cn/sqs/pricing/)。
仅支持[替换模板](iot-substitution-templates.md)：API 且 Amazon CLI 仅支持
`useBase64`
将该参数设置为 `true` 以配置规则操作，以便在将数据写入 Amazon SQS 队列之前对消息数据进行 base64 编码。默认值为 `false`。
支持[替换模板](iot-substitution-templates.md)：否
`roleArn`
允许访问 Amazon SQS 队列的 IAM 角色。有关更多信息，请参阅 [要求](#sqs-rule-action-requirements)。
支持[替换模板](iot-substitution-templates.md)：否
## 示例
以下 JSON 示例在 Amazon IoT 规则中定义了 SQS 操作。
```
{
"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"
}
}
]
}
}
```
以下 JSON 示例定义了在 Amazon IoT 规则中使用替换模板的 SQS 操作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sqs": {
"queueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/${topic()}",
"useBase64": true,
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sqs"
}
}
]
}
}
```
## 另请参阅
+ *《Amazon Simple Queue Service 开发人员指南》*中的[什么是 Amazon Simple Queue Service？](https://docs.amazonaws.cn/AWSSimpleQueueService/latest/SQSDeveloperGuide/)
# Step Functions
Step Functions (`stepFunctions`) 操作启动 Amazon Step Functions 状态机。
## 要求
此规则操作具有以下要求：
+ Amazon IoT 可以代入执行`states:StartExecution`操作的 IAM 角色。有关更多信息，请参阅 [授予 Amazon IoT 规则所需的访问权限](iot-create-role.md)。
在 Amazon IoT 控制台中，您可以选择或创建 Amazon IoT 允许执行此规则操作的角色。
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
`stateMachineName`
开始执行 Step Functions 状态机的名称。
仅支持[替换模板](iot-substitution-templates.md)：API 且 Amazon CLI 仅支持
`executionNamePrefix`
（可选）将为状态机执行操作指定名称，由此前缀后加 UUID 组成。如果未提供名称，Step Functions 会自动为每次状态机执行创建一个唯一的名称。
支持[替换模板](iot-substitution-templates.md)：是
`roleArn`
授予启动状态机的 Amazon IoT 权限的角色的 ARN。有关更多信息，请参阅 [要求](#stepfunctions-rule-action-requirements)。
支持[替换模板](iot-substitution-templates.md)：否
## 示例
以下 JSON 示例在 Amazon IoT 规则中定义了 Step Functions 操作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"stepFunctions": {
"stateMachineName": "myStateMachine",
"executionNamePrefix": "myExecution",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_step_functions"
}
}
]
}
}
```
## 另请参阅
+ [什么是 Amazon Step Functions？](https://docs.amazonaws.cn/step-functions/latest/dg/) 在《*Amazon Step Functions 开发者指南》*中
# Timestream
Timestream 规则操作将 MQTT 消息中的属性（度量）写入 Amazon Timestream 表。有关 Amazon Timestream 的更多信息，请参阅[什么是 Amazon Timestream？](https://docs.amazonaws.cn/timestream/latest/developerguide/what-is-timestream.html)。
**注意**
Amazon Timestream 并非在所有版本中都 Amazon Web Services 区域可用。如果 Amazon Timestream 在您所在区域中不可用，则它将不会显示在规则操作列表中。
此规则存储在 Timestream 数据库中的属性是由规则的查询语句生成的属性。对查询语句结果中每个属性的值进行解析以推断其数据类型（如 [迪纳摩 DBv2](dynamodb-v2-rule-action.md) 操作）。每个属性的值都写入到 Timestream 表中自己的记录中。要指定或更改属性的数据类型，请在查询语句中使用 [`cast()`](iot-sql-functions.md#iot-sql-function-cast) 函数。有关每条 Timestream 记录内容的更多信息，请参阅 [Timestream 记录内容](#timestream-rule-action-data)。
**注意**
对于 SQL V2（2016-03-23），整数数字值，例如 `10.0`，将转换为整数表示形式 (`10`)。显式将它们转换为 `Decimal` 值，例如通过使用 [cast()](iot-sql-functions.md#iot-sql-function-cast) 函数，不会阻止此行为--结果仍然是 `Integer` 值。这可能会导致类型不匹配错误，从而阻止在 Timestream 数据库中记录数据。要将整数数值处理为 `Decimal` 值，请使用 SQL V1（2015-10-08）作为规则查询语句。
**注意**
Timestream 规则操作可以写入 Amazon Timestream 表的值的最大数目为 100。有关更多信息，请参阅 [Amazon Timestream 配额参考](https://docs.amazonaws.cn//timestream/latest/developerguide/ts-limits.html#limits.default)。
## 要求
此规则操作具有以下要求：
+ Amazon IoT 可以代入执行`timestream:DescribeEndpoints`和`timestream:WriteRecords`操作的 IAM 角色。有关更多信息，请参阅 [授予 Amazon IoT 规则所需的访问权限](iot-create-role.md)。
在 Amazon IoT 控制台中，您可以选择、更新或创建 Amazon IoT 允许执行此规则操作的角色。
+ 如果您使用客户- Amazon KMS 来加密 Timestream 中的静态数据，则该服务必须有权代表呼叫者使用这些数据。 Amazon KMS key 有关更多信息，请参阅[Amazon 服务如何使用 Amazon KMS](https://docs.amazonaws.cn/kms/latest/developerguide/service-integration.html)。
## 参数
使用此操作创建 Amazon IoT 规则时，必须指定以下信息：
`databaseName`
Amazon Timestream 数据库的名称，该数据库中具有用于接收此操作创建的记录的表。另请参阅`tableName`。
支持[替换模板](iot-substitution-templates.md)： Amazon CLI 仅支持 API
`dimensions`
写入每个度量记录的时间序列的元数据属性。例如，EC2 实例的名称和可用区或风力涡轮机制造商的名称都是维度。
`name`
元数据维度名称。这是数据库表记录中列的名称。
维度不能命名为：`measure_name`、`measure_value` 或者 `time`。这些是预留的名称。维度名称不能以 `ts_` 或者 `measure_value` 开头，并且它们不能包含冒号 (`:`) 字符。
支持[替换模板](iot-substitution-templates.md)：否
`value`
在数据库记录的此列中写入的值。
支持[替换模板](iot-substitution-templates.md)：是
`roleArn`
角色的 Amazon 资源名称（ARN），该角色授予 Amazon IoT 写入 Timestream 数据库表的权限。有关更多信息，请参阅 [要求](#timestream-rule-action-requirements)。
支持[替换模板](iot-substitution-templates.md)：否
`tableName`
要将度量记录写入的数据库表的名称。另请参阅`databaseName`。
支持[替换模板](iot-substitution-templates.md)： Amazon CLI 仅支持 API
`timestamp`
用于条目的时间戳的值。如果为空，则使用处理条目的时间。
`unit`
`value` 中描述的表达式生成的时间戳值的精度。
有效值：`SECONDS` \$1 `MILLISECONDS` \$1`MICROSECONDS` \$1 `NANOSECONDS`。默认值为 `MILLISECONDS`。
`value`
返回长纪元时间值的表达式。
您可以使用 [time\$1to\$1epoch(String, String)](iot-sql-functions.md#iot-sql-function-time-to-epoch) 函数从消息负载中传递的日期或时间值创建有效的时间戳。
## Timestream 记录内容
通过此操作写入 Amazon Timestream 表的数据包括时间戳、Timestream 规则操作中的元数据以及规则查询语句的结果。
对于查询语句结果中的每个属性（度量），此规则操作将记录写入具有这些列的指定 Timestream 表。
| 列名称 | 属性类型 | 值 | 评论 |
| --- | --- | --- | --- |
| *dimension-name* | 维度 | 在 Timestream 规则操作条目中指定的值。 | 每个**维度**都会在规则操作条目中指定的 Timestream 数据库中创建一个具有维度名称的列。 |
| measure\$1name | MEASURE\$1NAME | 属性的名称 | 查询语句结果中的属性名称，其值已在 `measure_value::data-type` 列。 |
| 测量值:: *data-type* | MEASURE\$1VALUE | 查询语句结果中属性的值。属性的名称位于 `measure_name` 列。 | 该值被解释\$1 并强制转换为最合适的匹配：`bigint`、`boolean`、`double` 或 `varchar`。Amazon Timestream 为每种数据类型创建一个单独的列。消息中的值可以转换为另一个数据类型，方法是在规则的查询语句中使用 [`cast()`](iot-sql-functions.md#iot-sql-function-cast) 函数。 |
| 时间 | TIMESTAMP | 数据库中记录的日期和时间。 | 此值由规则引擎或 `timestamp` 属性分配（如果已定义）。 |
\$1 从消息有效载荷读取的属性值解释如下。请参阅 [示例](#timestream-rule-action-examples)，了解各个案例的说明。
+ 一个无引号的 `true` 或者 `false` 值将被解释为 `boolean` 类型。
+ 十进制数字被解释为 `double` 类型。
+ 没有小数点的数值被解释为 `bigint` 类型。
+ 带引号的字符串被解释为 `varchar` 类型。
+ 对象和数组值将转换为 JSON 字符串并存储为 `varchar` 类型。
## 示例
以下 JSON 示例定义了在规则中使用替换模板的 Timestream Amazon IoT 规则操作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'iot/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"timestream": {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_timestream",
"tableName": "devices_metrics",
"dimensions": [
{
"name": "device_id",
"value": "${clientId()}"
},
{
"name": "device_firmware_sku",
"value": "My Static Metadata"
}
],
"databaseName": "record_devices"
}
}
]
}
}
```
将上一示例中定义的 Timestream 主题规则操作与以下消息有效载荷结合使用会使得 Amazon Timestream 记录写入下表中。
```
{
"boolean_value": true,
"integer_value": 123456789012,
"double_value": 123.456789012,
"string_value": "String value",
"boolean_value_as_string": "true",
"integer_value_as_string": "123456789012",
"double_value_as_string": "123.456789012",
"array_of_integers": [23,36,56,72],
"array of strings": ["red", "green","blue"],
"complex_value": {
"simple_element": 42,
"array_of_integers": [23,36,56,72],
"array of strings": ["red", "green","blue"]
}
}
```
下表显示了使用指定主题规则操作处理先前创建消息有效载荷的数据库列和记录。`device_firmware_sku` 和 `device_id` 列是主题规则操作中定义的维度。Timestream 主题规则操作将创建 `time` 列以及 `measure_name` 和 `measure_value::*` 列，它将使用主题规则操作的查询语句结果中的值来填充这些值。
| device\$1firmware\$1sku | device\$1id | measure\$1name | measure\$1value::bigint | measure\$1value::varchar | measure\$1value::double | measure\$1value::boolean | 时间 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 我的静态元数据 | iotcon EXAMPLE738 sole-159 -0 | complex\$1value | - | \$1"simple\$1element":42,"array\$1of\$1integers":[23,36,56,72],"array of strings":["red","green","blue"]\$1 | - | - | 2020-08-26 22:42:16.423000000 |
| 我的静态元数据 | iotcon EXAMPLE738 sole-159 -0 | integer\$1value\$1as\$1string | - | 123456789012 | - | - | 2020-08-26 22:42:16.423000000 |
| 我的静态元数据 | iotcon EXAMPLE738 sole-159 -0 | boolean\$1value | - | - | - | TRUE | 2020-08-26 22:42:16.423000000 |
| 我的静态元数据 | iotcon EXAMPLE738 sole-159 -0 | integer\$1value | 123456789012 | - | - | - | 2020-08-26 22:42:16.423000000 |
| 我的静态元数据 | iotcon EXAMPLE738 sole-159 -0 | string\$1value | - | 字符串值 | - | - | 2020-08-26 22:42:16.423000000 |
| 我的静态元数据 | iotcon EXAMPLE738 sole-159 -0 | array\$1of\$1integers | - | [23,36,56,72] | - | - | 2020-08-26 22:42:16.423000000 |
| 我的静态元数据 | iotcon EXAMPLE738 sole-159 -0 | 字符串数组 | - | ["red","green","blue"] | - | - | 2020-08-26 22:42:16.423000000 |
| 我的静态元数据 | iotcon EXAMPLE738 sole-159 -0 | boolean\$1value\$1as\$1string | - | TRUE | - | - | 2020-08-26 22:42:16.423000000 |
| 我的静态元数据 | iotcon EXAMPLE738 sole-159 -0 | double\$1value | - | - | 123.456789012 | - | 2020-08-26 22:42:16.423000000 |
| 我的静态元数据 | iotcon EXAMPLE738 sole-159 -0 | double\$1value\$1as\$1string | - | 123.45679 | - | - | 2020-08-26 22:42:16.423000000 |
## 排除规则问题
如果您对规则有疑问，我们建议您激活 CloudWatch Logs。通过分析您的日志，您可以确定问题是否与授权相关，或者是否为诸如 WHERE 子句状态不匹配的问题。有关更多信息，请参阅[设置 CloudWatch 日志](https://docs.amazonaws.cn/iot/latest/developerguide/cloud-watch-logs.html)。
# 使用规则访问跨账户资源 Amazon IoT
访问跨账户资源
您可以配置跨账户访问 Amazon IoT 规则，以便在一个账户的 MQTT 主题上提取的数据可以路由到另一个账户的 Amazon 服务，例如 Amazon SQS 和 Lambda。以下内容说明如何设置跨账户数据提取 Amazon IoT 规则，从一个账户中的 MQTT 主题到另一个账户中的目的地。
跨账户规则可以在目标资源上使用[基于资源的权限](https://docs.amazonaws.cn/IAM/latest/UserGuide/access_controlling.html#TypesPermissions)。因此，只有支持基于资源的权限的目标才能启用带 Amazon IoT 规则的跨账户访问权限。支持的目的地包括 Amazon SQS、Amazon SNS、Amazon S3 和 Amazon Lambda。
**注意**
对于支持的目标（Amazon SQS 除外），您必须将规则定义 Amazon Web Services 区域 为与其他服务的资源相同，这样规则操作才能与该资源交互。有关 Amazon IoT 规则操作的更多信息，请参阅[Amazon IoT 规则操作](iot-rule-actions.md)。有关规则的 SQS 操作的更多信息，请参阅[SQS](sqs-rule-action.md)。
## 先决条件
+ 熟悉 [Amazon IoT 规则](https://docs.amazonaws.cn/iot/latest/developerguide/iot-rules.html)
+ 了解 IAM [用户](https://docs.amazonaws.cn/IAM/latest/UserGuide/introduction_identity-management.html)、[角色](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_roles.html)和[基于资源的权限](https://docs.amazonaws.cn/IAM/latest/UserGuide/access_permissions.html#TypesPermissions)
+ 安装 [Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/cli-chap-install.html)
## Amazon SQS 的跨账户设置
场景：账户 A 将 MQTT 消息中的数据发送到账户 B 的 Amazon SQS 队列。
| Amazon Web Services 账户 | 账户名称 | 说明 |
| --- | --- | --- |
| 1111-1111-1111 | 账户 A | 规则操作：sqs:SendMessage |
| 2222-2222-2222 | 账户 B | Amazon SQS 队列 [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/iot/latest/developerguide/accessing-cross-account-resources-using-rules.html) |
**注意**
[您的目标 Amazon SQS 队列不必与您的Amazon IoT 规则 Amazon Web Services 区域 相同。](https://docs.amazonaws.cn/iot/latest/developerguide/iot-rules.html)有关规则的 SQS 操作的更多信息，请参阅[SQS](sqs-rule-action.md)。
**执行账户 A 任务**
**备注**
要运行以下命令，您的 IAM 用户应具有 `iot:CreateTopicRule` 使用规则的 Amazon 资源名称（ARN）作为资源的权限，并且具有 `iam:PassRole` 操作使用资源作为角色的 ARN 的权限。
1. 使用账户 A 的 IAM 用户[配置 Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/cli-configure-quickstart.html)。
1. 创建信任 Amazon IoT 规则引擎的 IAM 角色，并附加允许访问账户 B 的 Amazon SQS 队列的策略。请参阅[授予 Amazon IoT 所需访问权限](https://docs.amazonaws.cn/iot/latest/developerguide/iot-create-role.html)中的示例命令和策略文档。
1. 要创建附加到主题的规则，请运行该[create-topic-rule 命令](https://docs.amazonaws.cn/cli/latest/reference/iot/create-topic-rule.html)。
```
aws iot create-topic-rule --rule-name myRule --topic-rule-payload file://./my-rule.json
```
下面是一个有效载荷文件示例，其中包含的规则会将发送至 `iot/test` 主题的所有消息插入指定 Amazon SQS 队列。SQL 语句筛选信息，角色 ARN 授予 Amazon IoT 写入 Amazon SQS 队列的权限。
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sqs": {
"queueUrl": "https://sqs.region.amazonaws.com/2222-2222-2222/ExampleQueue",
"roleArn": "arn:aws:iam::1111-1111-1111:role/my-iot-role",
"useBase64": false
}
}
]
}
```
有关如何在规则中定义 Amazon SQS 操作的更多信息，请参阅 Amazon IoT [Amazon IoT 规则操作-Amazon SQS。](https://docs.amazonaws.cn/iot/latest/developerguide/sqs-rule-action.html)
**执行账户 B 任务**
1. 使用账户 B 的 IAM 用户[配置 Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/cli-configure-quickstart.html)。
1. 要向账户 A 授予 Amazon SQS 队列资源的权限，请运行 [add-permission 命令](https://docs.amazonaws.cn/cli/latest/reference/sqs/add-permission.html)。
```
aws sqs add-permission --queue-url https://sqs.region.amazonaws.com/2222-2222-2222/ExampleQueue --label SendMessagesToMyQueue --aws-account-ids 1111-1111-1111 --actions SendMessage
```
## Amazon SNS 的跨账户设置
场景：账户 A 将 MQTT 消息中的数据发送到账户 B 的 Amazon SNS 主题。
| Amazon Web Services 账户 | 账户名称 | 说明 |
| --- | --- | --- |
| 1111-1111-1111 | 账户 A | 规则操作：sns:Publish |
| 2222-2222-2222 | 账户 B | Amazon SNS 主题 ARN：arn:aws:sns:region:2222-2222-2222:ExampleTopic |
**执行账户 A 任务**
**注意**
要运行以下命令，您的 IAM 用户应具有 `iot:CreateTopicRule` 的权限，拥有能够作为资源的规则 ARN，并具有 `iam:PassRole` 操作的权限，拥有作为角色 ARN 的资源。
1. 使用账户 A 的 IAM 用户[配置 Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/cli-configure-quickstart.html)。
1. 创建信任 Amazon IoT 规则引擎的 IAM 角色，并附加允许访问账户 B 的 Amazon SNS 主题的策略。有关命令和策略文档的示例，请参阅[授 Amazon IoT 予所需访问权限](https://docs.amazonaws.cn/iot/latest/developerguide/iot-create-role.html)。
1. 要创建附加到主题的规则，请运行该[create-topic-rule 命令](https://docs.amazonaws.cn/cli/latest/reference/iot/create-topic-rule.html)。
```
aws iot create-topic-rule --rule-name myRule --topic-rule-payload file://./my-rule.json
```
下面是一个有效载荷文件示例，其中包含的规则会将发送至 `iot/test` 主题的所有消息插入指定 Amazon SNS 主题。SQL 语句筛选消息，角色 ARN 授予 Amazon IoT 写入 Amazon SNS 主题的权限。
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:region:2222-2222-2222:ExampleTopic",
"roleArn": "arn:aws:iam::1111-1111-1111:role/my-iot-role"
}
}
]
}
```
有关如何在规则中定义 Amazon SNS 操作的更多信息，请参阅 Amazon IoT [Amazon IoT 规则操作-Amazon SNS](https://docs.amazonaws.cn/iot/latest/developerguide/sns-rule-action.html)。
**执行账户 B 任务**
1. 使用账户 B 的 IAM 用户[配置 Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/cli-configure-quickstart.html)。
1. 要向账户 A 授予 Amazon SNS 主题资源的权限，请运行 [add-permission 命令](https://docs.amazonaws.cn/cli/latest/reference/sns/add-permission.html)。
```
aws sns add-permission --topic-arn arn:aws:sns:region:2222-2222-2222:ExampleTopic --label Publish-Permission --aws-account-id 1111-1111-1111 --action-name Publish
```
## Amazon S3 的跨账户设置
场景：账户 A 将 MQTT 消息中的数据发送到账户 B 的 Amazon S3 存储桶。
| Amazon Web Services 账户 | 账户名称 | 说明 |
| --- | --- | --- |
| 1111-1111-1111 | 账户 A | 规则操作：s3:PutObject |
| 2222-2222-2222 | 账户 B | Amazon S3 存储桶 ARN：arn:aws:s3:::amzn-s3-demo-bucket |
**执行账户 A 任务**
**备注**
要运行以下命令，您的 IAM 用户应具有 `iot:CreateTopicRule` 的权限，能够将规则 ARN 作为资源，并具有 `iam:PassRole` 操作的权限，将资源作为角色 ARN。
1. 使用账户 A 的 IAM 用户[配置 Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/cli-configure-quickstart.html)。
1. 创建信任 Amazon IoT 规则引擎的 IAM 角色并附加允许访问账户 B 的 Amazon S3 存储桶的策略。有关命令和策略文档的示例，请参阅[授 Amazon IoT 予所需访问权限](https://docs.amazonaws.cn/iot/latest/developerguide/iot-create-role.html)。
1. 要创建附加到目标 S3 存储桶的规则，请运行[create-topic-rule 命令](https://docs.amazonaws.cn/cli/latest/reference/iot/create-topic-rule.html)。
```
aws iot create-topic-rule --rule-name my-rule --topic-rule-payload file://./my-rule.json
```
下面是一个有效载荷文件示例，其中包含的规则会将发送至 `iot/test` 主题的所有消息插入指定 Amazon S3 存储桶。SQL 语句筛选消息，角色 ARN 授予 Amazon IoT 将消息写入 Amazon S3 存储桶的权限。
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"s3": {
"bucketName": "amzn-s3-demo-bucket",
"key": "${topic()}/${timestamp()}",
"roleArn": "arn:aws:iam::1111-1111-1111:role/my-iot-role"
}
}
]
}
```
有关如何在规则中定义 Amazon S3 操作的更多信息，请参阅 Amazon IoT [Amazon IoT 规则操作-Amazon S3](https://docs.amazonaws.cn/iot/latest/developerguide/s3-rule-action.html)。
**执行账户 B 任务**
1. 使用账户 B 的 IAM 用户[配置 Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/cli-configure-quickstart.html)。
1. 创建信任账户 A 的主体的存储桶策略。
下面的示例有效载荷文件定义信任另一账户主体的存储桶策略。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AddCannedAcl",
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::123456789012:root"
]
},
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*"
}
]
}
```
有关更多信息，请参阅[存储桶策略示例](https://docs.amazonaws.cn/AmazonS3/latest/userguide/example-bucket-policies.html#example-bucket-policies-use-case-1)。
1. 要将存储桶策略附加到指定的存储桶，请运行[put-bucket-policy 命令](https://docs.amazonaws.cn/cli/latest/reference/s3api/put-bucket-policy.html)。
```
aws s3api put-bucket-policy --bucket amzn-s3-demo-bucket --policy file://./amzn-s3-demo-bucket-policy.json
```
1. 要跨账户访问工作，请确保您的**阻止所有公有访问**设置正确。有关更多信息，请参阅 [Amazon S3 安全性最佳实践](https://docs.amazonaws.cn/AmazonS3/latest/userguide/security-best-practices.html)。
## 的跨账户设置 Amazon Lambda
场景：账户 A 调用账户 B 的 Amazon Lambda 函数，传入 MQTT 消息。
| Amazon Web Services 账户 | 账户名称 | 说明 |
| --- | --- | --- |
| 1111-1111-1111 | 账户 A | 规则操作：lambda:InvokeFunction |
| 2222-2222-2222 | 账户 B | Lambda 函数 ARN： arn:aws:lambda:region:2222-2222-2222:function:example-function |
**执行账户 A 任务**
**注意**
要运行以下命令，您的 IAM 用户应具有 `iot:CreateTopicRule` 的权限，能够将规则 ARN 作为资源，以及对于 `iam:PassRole` 的权限，能够将资源作为角色 ARN。
1. 使用账户 A 的 IAM 用户[配置 Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/cli-configure-quickstart.html)。
1. 运行[create-topic-rule 命令](https://docs.amazonaws.cn/cli/latest/reference/iot/create-topic-rule.html)创建规则，定义对账户 B 的 Lambda 函数的跨账户访问权限。
```
aws iot create-topic-rule --rule-name my-rule --topic-rule-payload file://./my-rule.json
```
下面是一个有效载荷文件示例，其中包含的规则会将发送至 `iot/test` 主题的所有消息插入指定 Lambda 函数。SQL 语句筛选信息，角色 ARN 授予 Amazon IoT 将数据传入 Lambda 函数的权限。
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:region:2222-2222-2222:function:example-function"
}
}
]
}
```
有关如何在规则中定义 Amazon Lambda 操作的更多信息，请阅读 Amazon IoT [Amazon IoT 规则操作-Lambda](https://docs.amazonaws.cn/iot/latest/developerguide/lambda-rule-action.html)。
**执行账户 B 任务**
1. 使用账户 B 的 IAM 用户[配置 Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/cli-configure-quickstart.html)。
1. 运行 [Lambda 的添加权限命令](https://docs.amazonaws.cn/cli/latest/reference/lambda/add-permission.html)以授予 Amazon IoT 规则激活 Lambda 函数的权限。要运行以下命令，您的 IAM 用户应具有 `lambda:AddPermission` 操作的权限。
```
aws lambda add-permission --function-name example-function --region us-east-1 --principal iot.amazonaws.com --source-arn arn:aws:iot:region:1111-1111-1111:rule/example-rule --source-account 1111-1111-1111 --statement-id "unique_id" --action "lambda:InvokeFunction"
```
**选项：**
**--principal**
此字段授予 Amazon IoT （由`iot.amazonaws.com`）调用 Lambda 函数的权限。
**--source-arn**
此字段确认仅 Amazon IoT 中的 `arn:aws:iot:region:1111-1111-1111:rule/example-rule` 触发此 Lambda 函数，并且相同或不同账户中的任何其它规则都不能激活此 Lambda 函数。
**--source-account**
此字段确认仅代表 Amazon IoT 账户激活此 Lambda 函数。`1111-1111-1111`
**注意**
如果您看到一条错误消息在您的 Amazon Lambda 函数的控制台中 **Configuration**（配置）下显示：“The rule could not be found”（找不到规则），请忽略错误消息并继续测试连接。
# 错误处理（错误操作）
当 Amazon IoT 收到来自设备的消息时，规则引擎会检查该消息是否符合规则。如果匹配，将评估规则的查询语句，并激活规则的操作，同时传递查询语句的结果。
如果在激活操作时出现问题，则在为规则指定了错误操作的情况下，规则引擎将激活该错误操作。这可能在以下情况下发生：
+ 规则没有权限访问 Amazon S3 存储桶。
+ 用户错误导致超过 DynamoDB 预调配吞吐量。
**注意**
本主题中介绍的错误处理适用于[规则操作](iot-rule-actions.md)。要调试 SQL 问题（包括外部函数），可以设置 Amazon IoT 日志记录。有关更多信息，请参阅 [配置 Amazon IoT 日志](configure-logging.md)。
## 错误操作消息格式
对于每个规则和每条消息，会生成一条消息。例如，如果同一个规则中的两个规则操作失败，则错误操作将收到包含这两项错误的一条消息。
错误操作消息示例如下所示。
```
{
"ruleName": "TestAction",
"topic": "testme/action",
"cloudwatchTraceId": "7e146a2c-95b5-6caf-98b9-50e3969734c7",
"clientId": "iotconsole-1511213971966-0",
"base64OriginalPayload": "ewogICJtZXNzYWdlIjogIkhlbGxvIHZyb20gQVdTIElvVCBjb25zb2xlIgp9",
"failures": [
{
"failedAction": "S3Action",
"failedResource": "us-east-1-s3-verify-user",
"errorMessage": "Failed to put S3 object. The error received was The specified bucket does not exist (Service: Amazon S3; Status Code: 404; Error Code: NoSuchBucket; Request ID: 9DF5416B9B47B9AF; S3 Extended Request ID: yMah1cwPhqTH267QLPhTKeVPKJB8BO5ndBHzOmWtxLTM6uAvwYYuqieAKyb6qRPTxP1tHXCoR4Y=). Message arrived on: error/action, Action: s3, Bucket: us-east-1-s3-verify-user, Key: \"aaa\". Value of x-amz-id-2: yMah1cwPhqTH267QLPhTKeVPKJB8BO5ndBHzOmWtxLTM6uAvwYYuqieAKyb6qRPTxP1tHXCoR4Y="
}
]
}
```
ruleName
触发错误操作的规则的名称。
topic
收到原始消息的主题。
cloudwatchTraceId
引用错误的唯一身份登录 CloudWatch。
clientId
消息发布程序的客户端 ID。
base64 OriginalPayload
Base64 编码的原始消息有效载荷。
failures
failedAction
无法完成的操作的名称（例如，“S3Action”）。
failedResource
资源的名称（例如 S3 存储桶的名称）。
errorMessage
错误的描述和说明。
## 错误操作示例
下面是一个具有添加的错误操作的规则示例。以下规则具有将消息数据写入 DynamoDB 表的操作，以及将数据写入 Amazon S3 存储桶的错误操作：
```
{
"sql" : "SELECT * FROM ..."
"actions" : [{
"dynamoDB" : {
"table" : "PoorlyConfiguredTable",
"hashKeyField" : "AConstantString",
"hashKeyValue" : "AHashKey"}}
],
"errorAction" : {
"s3" : {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3",
"bucketName" : "message-processing-errors",
"key" : "${replace(topic(), '/', '-') + '-' + timestamp() + '-' + newuuid()}"
}
}
}
```
可以在错误操作的 SQL 语句中使用任何[函数](iot-sql-functions.md)或[替换模板](https://docs.amazonaws.cn//iot/latest/developerguide/iot-substitution-templates.html)，包括外部函数：[https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda](https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda)、[https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data](https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data)、[https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow](https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow)、[https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret](https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret)、[https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning](https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning)、和[https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64](https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64)。如果错误操作需要调用外部函数，则调用错误操作可能会导致产生针对外部函数的额外账单。
有关规则以及如何指定错误操作的更多信息，请参阅[创建 Amazon IoT 规则](https://docs.amazonaws.cn//iot/latest/developerguide/iot-create-rule.html)。
有关使用 CloudWatch 监控规则成功或失败的更多信息，请参阅[Amazon IoT 指标和维度](metrics_dimensions.md)。
# 借助基本摄取功能，降低消息收发成本
基本摄取
您可以使用基本摄取功能，将设备数据安全地发送到 [Amazon IoT 规则动作](iot-rule-actions.md)所支持的 Amazon Web Services 服务，而不会产生[消息收发成本](https://www.amazonaws.cn/iot-core/pricing/)。基本摄取功能通过从摄取路径中删除发布/订阅消息代理来优化数据流。
基本摄取功能可以从设备或应用程序发送消息。这些消息的主题名称以 `$aws/rules/rule_name` 开头（表示其前三个级别），其中 `rule_name` 是您要调用的 Amazon IoT 规则的名称。
您可以借助基本摄取功能来使用现有规则，方法为将基本摄取前缀（`$aws/rules/rule_name`）添加到您用于调用规则的消息主题。例如，如果您有名为 `BuildingManager` 的规则且它由主题类似于 `Buildings/Building5/Floor2/Room201/Lights`（`"sql": "SELECT * FROM 'Buildings/#'"`）的消息调用，那么通过发送主题为 `$aws/rules/BuildingManager/Buildings/Building5/Floor2/Room201/Lights` 的消息，您就可以使用基本摄取功能调用相同规则。
**注意**
您的设备和规则无法订阅基本摄取预留主题。例如，不发出 Amazon IoT Device Defender 指标 `num-messages-received` 指标，因为它不支持订阅主题。有关更多信息，请参阅 [保留的主题](reserved-topics.md)。
如果您需要发布/订阅代理来将消息分配给多个订阅者（例如，将消息传送到其它设备以及规则引擎），则应继续使用 Amazon IoT 消息代理来处理消息分配。但是，请确保在基本摄取主题以外的主题上发布您的消息。
## 使用基本摄取功能
使用基本摄取功能之前，请验证您的设备或应用程序正在使用对 `$aws/rules/*` 具有发布权限的[策略](iot-policies.md)。您也可以为策略中具有 `$aws/rules/rule_name/*` 的各个规则指定权限。否则，您的设备和应用程序可以继续使用与 Amazon IoT Core 的现有连接。
当消息到达规则引擎时，从基本摄取功能调用的规则与通过消息代理订阅调用的规则之间的实现或错误处理没有任何区别。
您可以创建与基本摄取搭配使用的规则。记住以下内容：
+ 基本摄取主题的初始前缀 (`$aws/rules/rule_name`) 不可用于 [topic(Decimal)](iot-sql-functions.md#iot-function-topic) 函数。
+ 如果您定义的规则仅通过基本摄取功能来调用，则 `FROM` 子句在 `rule` 定义的 `sql` 字段中是可选的。如果规则还由必须通过消息代理发送的其他消息来调用（例如，因为这些其他消息必须分配给多个订阅者），则其仍是必要项目。有关更多信息，请参阅 [Amazon IoT SQL 参考](iot-sql-reference.md)。
+ 基本摄取主题的前三个级别 (`$aws/rules/rule_name`) 不计入 8 个分段长度限制或针对主题的 256 个总字符限制。否则，应用 [Amazon IoT 限制](https://docs.amazonaws.cn/general/latest/gr/iot-core.html#limits_iot)中记录的相同限制。
+ 如果所收到消息的 Basic Ingest 主题指定了非活动或不存在的规则，则会在 Amazon CloudWatch 日志中创建错误日志来帮助您进行调试。有关更多信息，请参阅 [规则引擎日志条目](cwl-format.md#rule-engine-logs)。将指示 `RuleNotFound` 指标，您可以在该指标上创建警报。有关更多信息，请参阅[规则指标](metrics_dimensions.md#rulemetrics)中的“规则指标”。
+ 您仍可以使用 QoS 1 在基本摄取主题上进行发布。在消息成功传送到规则引擎后，您会收到 PUBACK。收到 PUBACK 并不意味着您的规则操作成功完成。您可以配置错误操作以在操作运行期间处理错误。有关更多信息，请参阅 [错误处理（错误操作）](rule-error-handling.md)。
# Amazon IoT SQL 参考
在中 Amazon IoT，规则是使用类似 SQL 的语法定义的。SQL 语句由三类子句组成：
**SET**
（可选）定义可在整个 SQL 语句和替换模板中重复使用的变量。使用表达式为变量赋值。在 SELECT 和 WHERE 子句以及操作替换模板中引用这些变量。
SET 子句支持[数据类型](iot-sql-data-types.md)[运算符](iot-sql-operators.md)、[函数](iot-sql-functions.md)、、[文本](iot-sql-literals.md)、[Case 语句](iot-sql-case.md)、[JSON 扩展](iot-sql-json.md)、、[变量](iot-sql-set.md#iot-sql-set-usage)和[嵌套对象查询](iot-sql-nested-queries.md)。
**SELECT**
（必填）从传入消息有效载荷提取信息并执行信息转换。要使用的消息由[主题筛选条件](topics.md#topicfilters)在 FROM 子句中指定。
SELECT 子句支持[数据类型](iot-sql-data-types.md)[运算符](iot-sql-operators.md)[函数](iot-sql-functions.md)、[文本](iot-sql-literals.md)、、[Case 语句](iot-sql-case.md)、[JSON 扩展](iot-sql-json.md)、[替换模板](iot-substitution-templates.md)、、、[嵌套对象查询](iot-sql-nested-queries.md)、[变量](iot-sql-set.md#iot-sql-set-usage)和[二进制有效载荷](binary-payloads.md)。
**FROM**
MQTT 消息[主题筛选条件](topics.md#topicfilters)，用于标识要从中提取数据的消息。对于发送到符合此处指定的主题筛选条件的 MQTT 主题的每条消息，将激活该规则。对于通过消息代理传递的消息所激活的规则是必需的。对于仅使用[基本摄取](iot-basic-ingest.md)特征激活的规则是可选的。
**WHERE**
（可选）添加用于确定是否执行规则指定的操作的条件逻辑。
WHERE 子句支持[数据类型](iot-sql-data-types.md)[运算符](iot-sql-operators.md)、[函数](iot-sql-functions.md)、[文本](iot-sql-literals.md)、[Case 语句](iot-sql-case.md)、、[JSON 扩展](iot-sql-json.md)、、[变量](iot-sql-set.md#iot-sql-set-usage)和[嵌套对象查询](iot-sql-nested-queries.md)。
SQL 语句的示例如下所示：
```
SELECT color AS rgb FROM 'topic/subtopic' WHERE temperature > 50
```
MQTT 消息（也称为传入有效载荷）的示例如下所示：
```
{
"color":"red",
"temperature":100
}
```
如果此消息在 `'topic/subtopic'` 主题上发布，则触发规则并评估 SQL 语句。如果 `color` 属性大于 50，SQL 语句将提取 `"temperature"` 属性的值。WHERE 子句指定条件 `temperature > 50`。`AS` 关键字将 `"color"` 属性重命名为 `"rgb"`。结果（也称为*传出有效载荷*）如下所示：
```
{
"rgb":"red"
}
```
此数据随后将转发至规则的操作，在其中发送数据供后续处理。有关规则操作的更多信息，请参阅 [Amazon IoT 规则动作](iot-rule-actions.md)。
**注意**
Amazon IoT SQL 语法目前不支持注释。
包含空格的属性名称不能用作 SQL 语句中的字段名称。虽然传入有效载荷可以在属性名称中包含空格，但这些名称不能在 SQL 语句中使用。但是，如果您使用通配符 (\$1) 字段名称规范，它们将传递到传出有效载荷。
# SELECT 子句
SE Amazon IoT LECT 子句与 ANSI SQL SELECT 子句基本相同，但有一些细微的区别。
SELECT 子句支持[数据类型](iot-sql-data-types.md)[运算符](iot-sql-operators.md)[函数](iot-sql-functions.md)、[文本](iot-sql-literals.md)、[Case 语句](iot-sql-case.md)、、[JSON 扩展](iot-sql-json.md)、、[嵌套对象查询](iot-sql-nested-queries.md)、[变量](iot-sql-set.md#iot-sql-set-usage)和[二进制有效载荷](binary-payloads.md)。
您可以使用 SELECT 子句从传入 MQTT 消息中提取信息。也可以使用 `SELECT *` 检索整个传入消息有效载荷。例如：
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL statement: SELECT * FROM 'topic/subtopic'
Outgoing payload: {"color":"red", "temperature":50}
```
如果有效载荷是 JSON 对象，您可以参考对象中的键。您的传出有效载荷将包含键值对。例如：
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL statement: SELECT color FROM 'topic/subtopic'
Outgoing payload: {"color":"red"}
```
您可以使用 AS 关键字重命名键。例如：
```
Incoming payload published on topic 'topic/subtopic':{"color":"red", "temperature":50}
SQL:SELECT color AS my_color FROM 'topic/subtopic'
Outgoing payload: {"my_color":"red"}
```
您可以通过用逗号分隔来选择多个项目。例如：
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT color as my_color, temperature as fahrenheit FROM 'topic/subtopic'
Outgoing payload: {"my_color":"red","fahrenheit":50}
```
您可以通过在向传入有效载荷添加项目时包括“\$1”来选择多个项目。例如：
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT *, 15 as speed FROM 'topic/subtopic'
Outgoing payload: {"color":"red", "temperature":50, "speed":15}
```
您可以使用 `"VALUE"` 关键字来生成不属于 JSON 对象的传出有效载荷。使用 SQL 版本 `2015-10-08` 时，您只能选择一个项目。使用 SQL 版本 `2016-03-23` 或更高版本时，您还可以选择作为顶级对象输出的数组。
**Example**
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT VALUE color FROM 'topic/subtopic'
Outgoing payload: "red"
```
您可以使用 `'.'` 语法深入剖析传入有效载荷中的嵌套 JSON 对象。例如：
```
Incoming payload published on topic 'topic/subtopic': {"color":{"red":255,"green":0,"blue":0}, "temperature":50}
SQL: SELECT color.red as red_value FROM 'topic/subtopic'
Outgoing payload: {"red_value":255}
```
有关如何使用包含预留字符（如数字或连字符（减号）的 JSON 对象和属性名称的信息，请参阅 [JSON 扩展](iot-sql-json.md)
您可以使用函数（参阅 [函数](iot-sql-functions.md)）来转换传入有效载荷。您可以使用括号进行分组。例如：
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT (temperature - 32) * 5 / 9 AS celsius, upper(color) as my_color FROM 'topic/subtopic'
Outgoing payload: {"celsius":10,"my_color":"RED"}
```
# FROM 子句
FROM 子句在[主题](topics.md#topicnames)或[主题筛选条件](topics.md#topicfilters)中订阅您的规则。将主题或主题筛选条件用单引号（'）引起来。对于发送到符合此处指定的主题筛选条件的 MQTT 主题的每条消息，将触发该规则。可以使用主题筛选条件订阅一组类似的主题。
**示例**：
传入负载已发布至主题 `'topic/subtopic'`：`{temperature: 50}`
传入负载已发布至主题 `'topic/subtopic-2'`：`{temperature: 50}`
SQL：`"SELECT temperature AS t FROM 'topic/subtopic'"`。
该规则已订阅到 `'topic/subtopic'`，因此传入的有效载荷将传递给该规则。传递给规则操作的传出有效载荷为：`{t: 50}`。规则未订阅 `'topic/subtopic-2'`，因此在 `'topic/subtopic-2'` 上发布的消息不会触发规则。
**\$1 通配符示例：**
您可以使用“\$1”（多级）通配符来匹配一个或多个特定路径元素：
传入负载已发布至主题 `'topic/subtopic'`：`{temperature: 50}`。
传入负载已发布至主题 `'topic/subtopic-2'`：`{temperature: 60}`。
传入负载已发布至主题 `'topic/subtopic-3/details'`：`{temperature: 70}`。
传入负载已发布至主题 `'topic-2/subtopic-x'`：`{temperature: 80}`。
SQL：`"SELECT temperature AS t FROM 'topic/#'"`。
该规则订阅了以开头的任何主题，因此它会执行三次`'topic'`，向其操作发送（对于主题/副主题）、`{t: 50}`（对于主题/子主题2）和`{t: 60}`（for）的传出有效负载。`{t: 70}` topic/subtopic-3/details它未订阅 `'topic-2/subtopic-x'`，因此不会针对 `{temperature: 80}` 消息触发规则。
**\$1 通配符示例：**
您可以使用“\$1”（单级）通配符来匹配任一特定路径元素：
传入负载已发布至主题 `'topic/subtopic'`：`{temperature: 50}`。
传入负载已发布至主题 `'topic/subtopic-2'`：`{temperature: 60}`。
传入负载已发布至主题 `'topic/subtopic-3/details'`：`{temperature: 70}`。
传入负载已发布至主题 `'topic-2/subtopic-x'`：`{temperature: 80}`。
SQL：`"SELECT temperature AS t FROM 'topic/+'"`。
规则已订阅包含两个路径元素的所有主题，其中第一个元素为 `'topic'`。此规则将对发送至 `'topic/subtopic'` 和 `'topic/subtopic-2'` 的消息执行，但不对 `'topic/subtopic-3/details'`（它的级别比主题筛选条件更多）或 `'topic-2/subtopic-x'`（它不以 `topic` 开头）执行。
# SET 子句
使用 SET 子句定义存储表达式结果的变量。您可以在 SELECT 和 WHERE 子句以及替换模板中重复使用这些变量。这可以帮助您避免重复复杂的表达式并减少 SQL 语句中的函数调用次数。
SET 子句支持[数据类型](iot-sql-data-types.md)[运算符](iot-sql-operators.md)、[函数](iot-sql-functions.md)、、[文本](iot-sql-literals.md)、[Case 语句](iot-sql-case.md)、[JSON 扩展](iot-sql-json.md)、、[变量](#iot-sql-set-usage)和[嵌套对象查询](iot-sql-nested-queries.md)。
## SET 子句语法
SET 子句必须出现在您的 SQL 语句中的 SELECT 子句之前。使用以下语法：
```
SET @variable_name = expression [, @variable_name2 = expression2]
```
语法规则：
+ 变量名称的开头为 `@`
+ 变量名可以包含字母、数字和下划线
+ 变量名最长可为 64 个字符
+ 可以在单个 SET 子句中设置多个变量，用逗号分隔
+ 每个变量只能分配一次（变量是不可变的）
+ 每条 SQL 语句只能使用一次 SET 关键字
## 使用变量
定义变量后，可以在以下情况下使用它们：
+ 选择子句
+ WHERE 子句
+ 其他 SET 变量赋值
+ 操作替换模板
+ 错误操作替换模板
+ 嵌套的选择查询
+ 函数参数（某些参数，例如 roLearn 参数和切换类似函数模式的参数`transform("enrichArray", attributes, values)`不支持变量）
使用与 SET 子句中相同的`@variable_name`语法来引用变量。您还可以使用 JSON 扩展语法来访问包含对象的变量的属性，例如`@variable_name.property`。
## SET 子句示例
**变量的基本用法**
以下示例显示了按主题发布的有效负载`device/data`：`{"temp_fahrenheit": 75, "humidity": 60}`
SQL 语句：
```
SET @temp_celsius = (temp_fahrenheit - 32) * 5 / 9
SELECT @temp_celsius AS celsius, humidity FROM 'device/data'
```
传出有效载荷：`{"celsius": 23.89, "humidity": 60}`
**访问嵌入式 JSON 对象中的成员**
以下示例显示了按主题发布的有效负载`device/data`：`{"device1": {"deviceId":"weather_sensor", "deviceData": {"sensors": {"temp_fahrenheit": 75, "humidity": 60}, "location": [47.606,-122.332]}}}`
SQL 语句：
```
SET @device_sensor_data = device1.deviceData.sensors
SELECT @device_sensor_data.temp_fahrenheit AS temp_fahrenheit, @device_sensor_data.humidity as humidity, device1.deviceId as deviceId FROM 'device/data'
```
传出有效载荷：`{"temp_fahrenheit":75,"humidity":60,"deviceId":"weather_sensor"}`
有关如何使用 JSON 扩展的更多信息，请参阅 [JSON 扩展](iot-sql-json.md)
**避免重复的函数调用**
SET 变量有助于避免重复复杂的解码操作：
```
SET @decoded_data = decode(encode(*, 'base64'), 'proto', 'schema', 'schema.desc', 'message.proto', 'Message')
SELECT @decoded_data.sensor_id, @decoded_data.reading FROM 'device/protobuf'
WHERE @decoded_data.reading > 100
```
如果没有 SET 变量，则需要重复三次解码函数，这会超出函数调用限制。
**多个变量**
你可以在单个 SET 子句中定义多个变量，方法是用逗号分隔它们：
```
SET @user_data = get_user_properties(device_id), @threshold = 50
SELECT @user_data.name, temp_fahrenheit FROM 'sensors/+'
WHERE temp_fahrenheit > @threshold AND @user_data.active = true
```
**在替换模板中使用变量**
变量还可以在操作替换模板中使用，允许您在 SQL 语句和规则操作中重复使用计算值。
SQL 语句：
```
SET @temp_celsius = (temp_fahrenheit - 32) * 5 / 9
SELECT @temp_celsius AS celsius, humidity FROM 'device/data'
```
操作配置：
```
{
"s3": {
"roleArn": "arn:aws:iam::123456789012:role/testRuleRole",
"bucketName": "bucket",
"key": "temperature-data/${device_id}/temp-${@temp_celsius}C.json"
}
}
```
在此示例中，在替换模板中使用 SET 变量`@temp_celsius`来构造 S3 操作的关键字段。
**非 JSON 负载使用情况**
SET 变量不直接支持非 JSON 有效负载，因此必须先对有效负载进行编码或解码：
```
SET @encoded_payload = encode(*, 'base64')
SELECT @encoded_payload AS raw_data FROM 'device/binary'
```
有关如何使用非 JSON 负载的更多信息，请参阅 [使用二进制有效载荷](binary-payloads.md)
## 设定条款限制
以下限制适用于 SET 变量：
+ 每条 SQL 语句最多有 10 个唯一变量
+ 最大可变值大小为 128 kiB（缩小后的 UTF-8 JSON 字符串）
+ 所有变量的最大总值大小为 128 KiB
+ 变量名限制为 64 个字符
+ 变量可以直接接受 JSON 负载（必须首先对非 JSON 负载进行编码/解码）
# WHERE 子句
WHERE 子句可确定是否执行规则指定的操作。如果 WHERE 子句的计算结果为 true，则执行规则操作。否则，不执行规则操作。
WHERE 子句支持[数据类型](iot-sql-data-types.md)[运算符](iot-sql-operators.md)、[函数](iot-sql-functions.md)、[文本](iot-sql-literals.md)、[Case 语句](iot-sql-case.md)、、[JSON 扩展](iot-sql-json.md)、、[变量](iot-sql-set.md#iot-sql-set-usage)和[嵌套对象查询](iot-sql-nested-queries.md)。
**示例**：
传入有效载荷已发布至 `topic/subtopic`：`{"color":"red", "temperature":40}`。
SQL：`SELECT color AS my_color FROM 'topic/subtopic' WHERE temperature > 50 AND color <> 'red'`。
在这种情况下，规则将被触发，但不会执行规则所指定的操作。没有传出的有效载荷。
您可以在 WHERE 子句中使用函数和运算符。但是，您无法引用在 SELECT 中通过 AS 关键字创建的任何别名。首先评估 WHERE 语句，以确定是否评估 SELECT。
**带非 JSON 有效载荷的示例：**
传入的非 JSON 有效载荷，发布位置：“topic/subtopic”：“80”
SQL：``SELECT decode(encode(*, 'base64'), 'base64') AS value FROM 'topic/subtopic' WHERE decode(encode(*, 'base64'), 'base64') > 50`
在这种情况下，规则将被触发，并且将执行规则所指定的操作。传出的有效载荷将由 SELECT 子句转换为 JSON 有效载荷 `{"value":80}`。
# 数据类型
Amazon IoT 规则引擎支持所有 JSON 数据类型。
**支持的数据类型**
| Type | 含义 |
| --- | --- |
| Int | 离散的 Int。最大 34 位。 |
| Decimal | 精度为 34 位的 `Decimal`，最小非零数量级为 1E-999，最大数量级为 9.999…E999。 部分函数返回双精度 `Decimal` 值，而不是 34 位数字精度。 对于 SQL V2（2016-03-23），整数数字值，例如 `10.0`，将被处理为 `Int` 值 (`10`)，而不是预期的 `Decimal` 值 (`10.0`)。若要可靠地将整数数值处理为 `Decimal` 值，请使用 SQL V1（2015-10-08）作为规则查询语句。 |
| Boolean | True 或 False。 |
| String | UTF-8 字符串。 |
| Array | 不必为相同类型的一系列值。 |
| Object | 包含一个键和一个值的 JSON 值。键必须是字符串。值可以是任意类型。 |
| Null | Null 由 JSON 定义。它是表示缺少某个值的实际值。您必须通过使用 SQL 语句中 Null 关键字明确创建一个 Null 值。例如："SELECT NULL AS n FROM 'topic/subtopic'"。 |
| Undefined | 非值。在 JSON 中无法明确表示，只能忽略该值。例如，在对象 `{"foo": null}` 中，键“foo”返回 NULL，但键“bar”返回 `Undefined`。在内部，SQL 语言将 `Undefined` 作为值处理，但它在 JSON 中无法表示，因此，在序列化为 JSON 时，结果为 `Undefined`。 {"foo":null, "bar":undefined} 序列化为 JSON 如下： {"foo":null} 同样，`Undefined` 在被自身序列化时会转化为空字符串。使用无效参数（例如，错误的类型、错误的参数号等）调用的函数将返回 `Undefined`。 |
## 转换
下表列出当一个类型的值转换为另一个类型时（为函数提供错误类型的值时）返回的结果。例如，如果绝对值函数“abs”（期待的值类型为 `Int` 或 `Decimal`）被赋予 `String` 时，它会尝试遵循以下规则将 `String` 转换为 `Decimal`。在这种情况下，“abs（“-5.123”）”将被视为“abs（-5.123）”。
**注意**
不会尝试转换 `Array`、`Object`、`Null` 或 `Undefined`。
**To decimal**
| 参数类型 | 结果 |
| --- | --- |
| Int | 没有小数点的 Decimal。 |
| Decimal | 源值。 |
| Boolean | Undefined。（您可以明确使用 cast 函数使 true = 1.0，false = 0.0。) |
| String | SQL 引擎尝试将字符串解析为。Decimal Amazon IoT 尝试解析与正则表达式匹配的字符串:^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1。可自动转换为 Decimal 的字符串示例包括“0”、“-1.2”、“5E-12”。 |
| 数组 | Undefined. |
| 对象 | Undefined. |
| Null | Null. |
| 未定义 | Undefined. |
**To int**
| 参数类型 | 结果 |
| --- | --- |
| Int | 源值。 |
| Decimal | 源值都舍入到最接近的 Int。 |
| Boolean | Undefined。（您可以明确使用 cast 函数使 true = 1.0，false = 0.0。) |
| String | SQL 引擎尝试将字符串解析为。Decimal Amazon IoT 尝试解析与正则表达式匹配的字符串:^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1。“0”、“-1.2”、“5E-12” 都是自动转换为 Decimal s 的字符串的示例。 Amazon IoT 尝试将其转换为 aDecimal，然后将其中的小数位截断String为一个。Decimal Int |
| 数组 | Undefined. |
| 对象 | Undefined. |
| Null | Null. |
| 未定义 | Undefined. |
**To Boolean**
| 参数类型 | 结果 |
| --- | --- |
| Int | Undefined。（您可以明确使用 cast 函数使 0 = False，any\$1nonzero\$1value = True。） |
| Decimal | Undefined。（您可以明确使用 cast 函数使 0 = False，any\$1nonzero\$1value = True。） |
| Boolean | 原始值。 |
| String | “true” = True 和“false”= False（不区分大小写）。其它字符串值为 Undefined。 |
| 数组 | Undefined. |
| 对象 | Undefined. |
| Null | Undefined. |
| 未定义 | Undefined. |
**To string**
| 参数类型 | 结果 |
| --- | --- |
| Int | 标准表示法中 Int 的字符串表示形式。 |
| Decimal | 科学表示法中 Decimal 值的字符串表示。 |
| Boolean | “true”或“false”。均为小写。 |
| String | 原始值。 |
| 数组 | Array 序列化为 JSON。结果字符串为逗号分隔的列表，括在方括号中。String 带引号。Decimal、Int、Boolean 和 Null 不带引号。 |
| 对象 | 序列化为 JSON 的对象。结果字符串为键值对的逗号分隔列表，以大括号开头和结束。String 带引号。Decimal、Int、Boolean 和 Null 不带引号。 |
| Null | Undefined. |
| 未定义 | Undefined。 |
# 运算符
可以在 SELECT 和 WHERE 子句中使用以下运算符。
## AND 运算符
返回 `Boolean` 结果。执行逻辑与运算。如果左右操作数为 true，则返回 true。否则，返回 false。需要提供 `Boolean` 操作数或不区分大小写的“true”或“false”字符串操作数。
*语法：*` expression AND expression`。
**AND 运算符**
| 左侧操作数 | 右侧操作数 | Output |
| --- | --- | --- |
| Boolean | Boolean | Boolean。如果两个操作数均为 true，则为 true。否则为 false。 |
| String/Boolean | String/Boolean | 如果所有字符串均为“true”或“false”（不区分大小写），则它们将被转换为 Boolean 并作为 boolean AND boolean 正常处理。 |
| 其它值 | 其它值 | Undefined. |
## OR 运算符
返回 `Boolean` 结果。执行逻辑或运算。如果左右操作数至少有一个为 true，则返回 true。否则，返回 false。需要提供 `Boolean` 操作数或不区分大小写的“true”或“false”字符串操作数。
*语法：*` expression OR expression`。
**OR 运算符**
| 左侧操作数 | 右侧操作数 | Output |
| --- | --- | --- |
| Boolean | Boolean | Boolean。如果任意一个操作数为 true，则为 true。否则为 false。 |
| String/Boolean | String/Boolean | 如果所有字符串均为“true”或“false”（不区分大小写），则将其转换为布尔值并作为 boolean OR boolean 正常处理。 |
| 其它值 | 其它值 | Undefined. |
## NOT 运算符
返回 `Boolean` 结果。执行逻辑非运算。如果操作数为 false，则返回 true。否则返回 true。需要 `Boolean` 操作数或不区分大小写的“true”或“false”字符串操作数。
*语法：*`NOT expression`。
**NOT 运算符**
| 操作数 | Output |
| --- | --- |
| Boolean | Boolean。如果操作数为 false，则为 true。否则为 true。 |
| String | 如果字符串为“true”或“false”（不区分大小写），它将转换为对应的布尔值，并返回相反的值。 |
| 其它值 | Undefined. |
## IN 运算符
返回 `Boolean` 结果。您可以在 WHERE 子句中使用 IN 运算符来查看某个值是否与数组中的任何值匹配。如果找到匹配项，则返回 true，否则返回 false。
*语法：*` expression IN expression`。
**IN 运算符**
| 左侧操作数 | 右侧操作数 | Output |
| --- | --- | --- |
| Int/Decimal/String/Array/Object | Array | 如果在数组中找到 Integer/Decimal/String/Array/Object 元素，则为 true。否则为 false。 |
*示例*：
```
SQL: "select * from 'a/b' where 3 in arr"
JSON: {"arr":[1, 2, 3, "three", 5.7, null]}
```
在此示例中，条件子句 `where 3 in arr` 的计算结果将为 true，因为名为 `arr` 的数组中存在 3 。因此，在 SQL 语句中，`select * from 'a/b'` 将执行。此示例还显示了数组可以是异构的。
## EXISTS 运算符
返回 `Boolean` 结果。可以在条件子句中使用 EXISTS 运算符来测试子查询中是否存在元素。如果子查询返回一个或多个元素，则返回 true；如果子查询不返回任何元素，则返回 false。
*语法：*` expression`。
*示例*：
```
SQL: "select * from 'a/b' where exists (select * from arr as a where a = 3)"
JSON: {"arr":[1, 2, 3]}
```
在此示例中，条件子句 `where exists (select * from arr as a where a = 3)` 的计算结果将为 true，因为名为 `arr` 的数组中存在 3 。因此，在 SQL 语句中，`select * from 'a/b'` 将执行。
*示例*：
```
SQL: select * from 'a/b' where exists (select * from e as e where foo = 2)
JSON: {"foo":4,"bar":5,"e":[{"foo":1},{"foo":2}]}
```
在此示例中，条件子句 `where exists (select * from e as e where foo = 2)` 的计算结果将为 true，因为 JSON 对象中的 `e` 数组包含对象 `{"foo":2}`。因此，在 SQL 语句中，`select * from 'a/b'` 将执行。
## > 运算符
返回 `Boolean` 结果。如果左侧操作数大于右侧操作数，则返回 true。两个操作数将转换为 `Decimal`，然后进行比较。
*语法：* `expression > expression`。
**> 运算符**
| 左侧操作数 | 右侧操作数 | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean。如果左侧操作数大于右侧操作数，则为 true。否则为 false。 |
| String/Int/Decimal | String/Int/Decimal | 如果所有字符串可以转换为 Decimal，则为 Boolean。如果左侧操作数大于右侧操作数，则返回 true。否则为 false。 |
| 其它值 | Undefined. | Undefined. |
## >= operator
返回 `Boolean` 结果。如果左侧操作数大于等于右侧操作数，则返回 true。两个操作数将转换为 `Decimal`，然后进行比较。
*语法：*`expression >= expression`。
**>= operator**
| 左侧操作数 | 右侧操作数 | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean。如果左侧操作数大于等于右侧操作数，则为 true。否则为 false。 |
| String/Int/Decimal | String/Int/Decimal | 如果所有字符串可以转换为 Decimal，则为 Boolean。如果左侧操作数大于等于右侧操作数，则返回 true。否则为 false。 |
| 其它值 | Undefined. | Undefined. |
## < 运算符
返回 `Boolean` 结果。如果左侧操作数小于右侧操作数，则返回 true。两个操作数将转换为 `Decimal`，然后进行比较。
*语法：*`expression < expression`。
**< 运算符**
| 左侧操作数 | 右侧操作数 | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean。如果左侧操作数小于右侧操作数，则为 true。否则为 false。 |
| String/Int/Decimal | String/Int/Decimal | 如果所有字符串可以转换为 Decimal，则为 Boolean。如果左侧操作数小于右侧操作数，则返回 true。否则为 false。 |
| 其它值 | Undefined | Undefined |
## <= 运算符
返回 `Boolean` 结果。如果左侧操作数小于等于右侧操作数，则返回 true。两个操作数将转换为 `Decimal`，然后进行比较。
*语法：*`expression <= expression`。
**<= 运算符**
| 左侧操作数 | 右侧操作数 | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean。如果左侧操作数小于等于右侧操作数，则为 true。否则为 false。 |
| String/Int/Decimal | String/Int/Decimal | 如果所有字符串可以转换为 Decimal，则为 Boolean。如果左侧操作数小于等于右侧操作数，则返回 true。否则为 false。 |
| 其它值 | Undefined | Undefined |
## <> 运算符
返回 `Boolean` 结果。如果左右操作数不相等，则返回 true。否则返回 false。
*语法：*` expression <> expression`。
**<> 运算符**
| 左侧操作数 | 右侧操作数 | Output |
| --- | --- | --- |
| Int | Int | 如果左侧操作数不等于右侧操作数，则为 true。否则为 false。 |
| Decimal | Decimal | 如果左侧操作数不等于右侧操作数，则为 true。否则为 false。在比较之前，Int 会被转换为 Decimal。 |
| String | String | 如果左侧操作数不等于右侧操作数，则为 true。否则为 false。 |
| 数组 | 数组 | 如果各个操作数中的项不相等且顺序不同，则为 true。否则为 false |
| 对象 | 对象 | 如果各个操作数的键和值均不相等，则为 true。否则为 false。的顺序 keys/values 并不重要。 |
| Null | Null | False。 |
| 任意值 | Undefined | Undefined。 |
| Undefined | 任意值 | Undefined。 |
| 不匹配的类型 | 不匹配的类型 | True。 |
## = 运算符
返回 `Boolean` 结果。如果左右操作数相等，则返回 true。否则返回 false。
*语法：*` expression = expression`。
**= 运算符**
| 左侧操作数 | 右侧操作数 | Output |
| --- | --- | --- |
| Int | Int | 如果左侧操作数等于右侧操作数，则为 true。否则为 false。 |
| Decimal | Decimal | 如果左侧操作数等于右侧操作数，则为 true。否则为 false。在比较之前，Int 会被转换为 Decimal。 |
| String | String | 如果左侧操作数等于右侧操作数，则为 true。否则为 false。 |
| 数组 | 数组 | 如果各个操作数中的项相等且顺序相同，则为 true。否则为 false。 |
| 对象 | 对象 | 如果各个操作数的键和值相等，则为 true。否则为 false。的顺序 keys/values 并不重要。 |
| 任意值 | Undefined | Undefined. |
| Undefined | 任意值 | Undefined. |
| 不匹配的类型 | 不匹配的类型 | False。 |
## \$1 运算符
“\$1”是一个重载运算符。它可用于字符串联接或相加。
*语法：*` expression + expression`。
**\$1 运算符**
| 左侧操作数 | 右侧操作数 | Output |
| --- | --- | --- |
| String | 任意值 | 将右侧操作数转换为一个字符串，并联接到左侧操作数的末尾。 |
| 任意值 | String | 将左侧操作数转换为一个字符串，并将右侧操作数联接到转换后的左侧操作数的末尾。 |
| Int | Int | Int 值。将操作数相加。 |
| Int/Decimal | Int/Decimal | Decimal 值。将操作数相加。 |
| 其它值 | 其它值 | Undefined. |
## - 运算符
从左侧操作数中减去右侧操作数。
*语法：*` expression - expression`。
**- 运算符**
| 左侧操作数 | 右侧操作数 | Output |
| --- | --- | --- |
| Int | Int | Int 值。从左侧操作数中减去右侧操作数。 |
| Int/Decimal | Int/Decimal | Decimal 值。从左侧操作数中减去右侧操作数。 |
| String/Int/Decimal | String/Int/Decimal | 如果所有字符串都正确地转换为小数，则返回 Decimal 值。从左侧操作数中减去右侧操作数。否则返回 Undefined。 |
| 其它值 | 其它值 | Undefined. |
| 其它值 | 其它值 | Undefined. |
## \$1 运算符
左侧操作数乘以右侧操作数。
*语法：*` expression * expression`。
**\$1 运算符**
| 左侧操作数 | 右侧操作数 | Output |
| --- | --- | --- |
| Int | Int | Int 值。左侧操作数乘以右侧操作数。 |
| Int/Decimal | Int/Decimal | Decimal 值。左侧操作数乘以右侧操作数。 |
| String/Int/Decimal | String/Int/Decimal | 如果所有字符串都正确地转换为小数，则返回 Decimal 值。左侧操作数乘以右侧操作数。否则返回 Undefined。 |
| 其它值 | 其它值 | Undefined. |
## / 运算符
左侧操作数除以右侧操作数。
*语法：*` expression / expression`。
**/ 运算符**
| 左侧操作数 | 右侧操作数 | Output |
| --- | --- | --- |
| Int | Int | Int 值。左侧操作数除以右侧操作数。 |
| Int/Decimal | Int/Decimal | Decimal 值。左侧操作数除以右侧操作数。 |
| String/Int/Decimal | String/Int/Decimal | 如果所有字符串都正确地转换为小数，则返回 Decimal 值。左侧操作数除以右侧操作数。否则返回 Undefined。 |
| 其它值 | 其它值 | Undefined. |
## % 运算符
返回左侧操作数除以右侧操作数得到的余数。
*语法：*` expression % expression`。
**% 运算符**
| 左侧操作数 | 右侧操作数 | Output |
| --- | --- | --- |
| Int | Int | Int 值。返回左侧操作数除以右侧操作数得到的余数。 |
| String/Int/Decimal | String/Int/Decimal | 如果所有字符串都正确地转换为小数，则返回 Decimal 值。返回左侧操作数除以右侧操作数得到的余数。否则为 Undefined。 |
| 其它值 | 其它值 | Undefined. |
# 函数
您可以使用 SQL 表达式的 SELECT 或 WHERE 子句中的以下内置函数。
以下外部函数的计费方式等同于规则操作的计费：[https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda](https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda)、[https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb](https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb)、和[https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow](https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow)。仅当您[将 Protobuf 消息解码为 JSON](https://docs.amazonaws.cn//iot/latest/developerguide/binary-payloads.html#binary-payloads-protobuf) 时，您才需要为该 [https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64](https://docs.amazonaws.cn//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64) 函数付费。有关更多详细信息，请参考 [Amazon IoT Core 定价页面](https://www.amazonaws.cn/iot-core/pricing/)。
## abs(Decimal)
返回数字的绝对值。SQL 版本 2015-10-08 及更高版本支持。
示例：`abs(-5)` 返回 5。
****
| 参数类型 | 结果 |
| --- | --- |
| Int | Int，参数的绝对值。 |
| Decimal | Decimal，参数的绝对值。 |
| Boolean | Undefined. |
| String | Decimal。结果是参数的绝对值。如果字符串无法转换，则结果为 Undefined。 |
| 数组 | Undefined. |
| 对象 | Undefined. |
| Null | Undefined. |
| 未定义 | Undefined. |
## accountid()
以 `String` 形式返回拥有该规则的账户的 ID。SQL 版本 2015-10-08 及更高版本支持。
示例：
`accountid() ` = "123456789012"
## acos(Decimal)
以弧度为单位返回数字的反余弦值。在代入函数之前，`Decimal` 参数舍入到双精度。SQL 版本 2015-10-08 及更高版本支持。
示例：`acos(0)` = 1.5707963267948966
****
| 参数类型 | 结果 |
| --- | --- |
| Int | Decimal (双精度)，参数的反余弦值。虚数结果返回 Undefined。 |
| Decimal | Decimal (双精度)，参数的反余弦值。虚数结果返回 Undefined。 |
| Boolean | Undefined. |
| String | Decimal，参数的反余弦值。如果字符串无法转换，则结果为 Undefined。虚数结果返回 Undefined。 |
| 数组 | Undefined. |
| 对象 | Undefined. |
| Null | Undefined. |
| 未定义 | Undefined. |
## asin(Decimal)
以弧度为单位返回数字的反正弦值。在代入函数之前，`Decimal` 参数舍入到双精度。SQL 版本 2015-10-08 及更高版本支持。
示例：`asin(0)` = 0.0
****
| 参数类型 | 结果 |
| --- | --- |
| Int | Decimal (双精度)，参数的反正弦值。虚数结果返回 Undefined。 |
| Decimal | Decimal (双精度)，参数的反正弦值。虚数结果返回 Undefined。 |
| Boolean | Undefined. |
| String | Decimal (双精度)，参数的反正弦值。如果字符串无法转换，则结果为 Undefined。虚数结果返回 Undefined。 |
| 数组 | Undefined. |
| 对象 | Undefined. |
| Null | Undefined. |
| 未定义 | Undefined. |
## atan(Decimal)
以弧度为单位返回数字的反正切值。在代入函数之前，`Decimal` 参数舍入到双精度。SQL 版本 2015-10-08 及更高版本支持。
示例：`atan(0)` = 0.0
****
| 参数类型 | 结果 |
| --- | --- |
| Int | Decimal (双精度)，参数的反正切值。虚数结果返回 Undefined。 |
| Decimal | Decimal (双精度)，参数的反正切值。虚数结果返回 Undefined。 |
| Boolean | Undefined. |
| String | Decimal，参数的反正切值。如果字符串无法转换，则结果为 Undefined。虚数结果返回 Undefined。 |
| 数组 | Undefined. |
| 对象 | Undefined. |
| Null | Undefined. |
| 未定义 | Undefined. |
## atan2(Decimal, Decimal)
以弧度的形式返回 x 轴正方向与由两个参数定义的 (x,y) 点之间的角度。 逆时针的角，角度为正数（上半平面，y > 0），顺时针的角，角度为负数（下半平面，y < 0）。在代入函数之前，`Decimal` 参数舍入到双精度。SQL 版本 2015-10-08 及更高版本支持。
示例：`atan2(1, 0)` = 1.5707963267948966
****
| 参数类型 | 参数类型 | 结果 |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Decimal（双精度），x 轴和指定的 (x,y) 点之间的角度。 |
| Int/Decimal/String | Int/Decimal/String | Decimal，所描述点的反正切值。如果字符串无法转换，则结果为 Undefined。 |
| 其它值 | 其它值 | Undefined. |
## aws\$1lambda(functionArn, inputJson)
调用指定的 Lambda 函数并将 `inputJson` 传递给 Lambda 函数，并且返回 Lambda 函数生成的 JSON。
**参数**
| 参数 | 说明 |
| --- | --- |
| functionArn | 要调用的 Lambda 函数的 ARN。Lambda 函数必须返回 JSON 数据。 |
| inputJson | 传递到 Lambda 函数的 JSON 输入。要传递嵌套对象查询和文本，您必须使用 SQL 版本 2016-03-23。 |
您必须授予调用指定的 Lambda 函数的 Amazon IoT `lambda:InvokeFunction`权限。以下示例说明如何使用 Amazon CLI授予 `lambda:InvokeFunction` 权限：
```
aws lambda add-permission --function-name "function_name"
--region "region"
--principal iot.amazonaws.com
--source-arn arn:aws:iot:us-east-1:account_id:rule/rule_name
--source-account "account_id"
--statement-id "unique_id"
--action "lambda:InvokeFunction"
```
**add-permission** 命令的参数如下：
--function-name
Lambda 函数的名称。添加新的权限来更新函数的资源策略。
--region
您的账户的。 Amazon Web Services 区域
--principal
获取权限的主体。这应该是`iot.amazonaws.com`为了 Amazon IoT 允许调用 Lambda 函数。
--source-arn
规则的 ARN。您可以使用**get-topic-rule** Amazon CLI 命令获取规则的 ARN。
--source-account
定义规则 Amazon Web Services 账户 的地方。
--statement-id
唯一的语句标识符。
--action
要在此声明中允许的 Lambda 操作。要允许 Amazon IoT 调用 Lambda 函数，请指定 `lambda:InvokeFunction`。
**重要**
如果您在不提供`source-arn`或的情况下为 Amazon IoT 委托人添加权限`source-account`，则任何 Amazon Web Services 账户 使用您的 Lambda 操作创建规则的人都可以触发规则，从中调用您的 Lambda 函数。 Amazon IoT有关更多信息，请参阅 [Lambda 权限模型](https://docs.amazonaws.cn/lambda/latest/dg/intro-permission-model.html)。
假设 JSON 消息有效载荷如下所示：
```
{
"attribute1": 21,
"attribute2": "value"
}
```
`aws_lambda` 函数可用于调用 Lambda 函数，如下所示。
```
SELECT
aws_lambda("arn:aws:lambda:us-east-1:account_id:function:lambda_function", {"payload":attribute1}) as output FROM 'topic-filter'
```
如果您想要传递完整的 MQTT 消息有效载荷，您可以使用“\$1”指定 JSON 有效载荷，如下示例所示。
```
SELECT
aws_lambda("arn:aws:lambda:us-east-1:account_id:function:lambda_function", *) as output FROM 'topic-filter'
```
`payload.inner.element` 从在主题“topic/subtopic”上发布的消息中选择数据。
`some.value` 从 Lambda 函数生成的输出中选择数据。
**注意**
规则引擎限制 Lambda 函数的执行持续时间。从规则执行的 Lambda 函数调用应在 2000 毫秒内完成。
## bitand(Int, Int)
在两个 `Int`（转换成的）参数的位表示之间逐位执行与运算。SQL 版本 2015-10-08 及更高版本支持。
示例：`bitand(13, 5)` = 5
****
| 参数类型 | 参数类型 | 结果 |
| --- | --- | --- |
| Int | Int | Int，对两个参数逐位执行与运算。 |
| Int/Decimal | Int/Decimal | Int，对两个参数逐位执行与运算。所有非 Int 数字向下舍入至最近的 Int。如果任意参数不能转换为 Int，则结果为 Undefined。 |
| Int/Decimal/String | Int/Decimal/String | Int，对两个参数逐位执行与运算。所有字符串转换为小数并向下舍入至最近的 Int。如果转换失败，结果为 Undefined。 |
| 其它值 | 其它值 | Undefined. |
## bitor(Int, Int)
在两个参数的位表示之间逐位执行或运算。SQL 版本 2015-10-08 及更高版本支持。
示例：`bitor(8, 5)` = 13
****
| 参数类型 | 参数类型 | 结果 |
| --- | --- | --- |
| Int | Int | Int，对两个参数逐位执行或运算。 |
| Int/Decimal | Int/Decimal | Int，对两个参数逐位执行或运算。所有非 Int 数字向下舍入至最近的 Int。如果转换失败，结果为 Undefined。 |
| Int/Decimal/String | Int/Decimal/String | Int，对两个参数逐位执行或运算。所有字符串转换为小数并向下舍入至最近的 Int。如果转换失败，结果为 Undefined。 |
| 其它值 | 其它值 | Undefined. |
## bitxor(Int, Int)
在两个 `Int`（转换成的）参数的位表示之间逐位执行异或运算。SQL 版本 2015-10-08 及更高版本支持。
示例：`bitor(13, 5)` = 8
****
| 参数类型 | 参数类型 | 结果 |
| --- | --- | --- |
| Int | Int | Int，对两个参数逐位执行异或运算。 |
| Int/Decimal | Int/Decimal | Int，对两个参数逐位执行异或运算。非 Int 数字向下舍入至最近的 Int。 |
| Int/Decimal/String | Int/Decimal/String | Int，对两个参数逐位执行异或运算。字符串转换为小数并向下舍入到最近的 Int。如果任何转换失败，结果为 Undefined。 |
| 其它值 | 其它值 | Undefined. |
## bitnot(Int)
对 `Int`（转换成的）参数的位表示逐位执行非运算。SQL 版本 2015-10-08 及更高版本支持。
示例：`bitnot(13)` = 2
****
| 参数类型 | 结果 |
| --- | --- |
| Int | Int，对参数逐位执行非运算。 |
| Decimal | Int，对参数逐位执行非运算。Decimal 值会向下舍入至最近的 Int。 |
| String | Int，对参数逐位执行非运算。字符串转换为小数值并向下舍入至最近的 Int。如果任何转换失败，结果为 Undefined。 |
| 其它值 | 其它值。 |
## cast()
将值从一个数据类型转换为另一个数据类型。强制转换与标准转换大体相同，但是增加了在数字与布尔值之间进行强制转换的能力。如果 Amazon IoT 无法确定如何将一种类型转换为另一种类型，则结果为`Undefined`。SQL 版本 2015-10-08 及更高版本支持。格式：cast（*value*as*type*）。
示例：
`cast(true as Int) ` = 1
在调用 `cast` 时，“as”后面可能出现以下关键字：
**对于 SQL 版本 2015-10-08 和 2016-03-23**
| Keyword | 结果 |
| --- | --- |
| String | 将值强制转换为 String。 |
| Nvarchar | 将值强制转换为 String。 |
| 文本 | 将值强制转换为 String。 |
| Ntext | 将值强制转换为 String。 |
| varchar | 将值强制转换为 String。 |
| Int | 将值强制转换为 Int。 |
| 整数 | 将值强制转换为 Int。 |
| 双精度 | 将值强制转换为 Decimal（双精度）。 |
**此外，对于 SQL 版本 2016-03-23**
| Keyword | 结果 |
| --- | --- |
| Decimal | 将值强制转换为 Decimal。 |
| 布尔型 | 将值强制转换为 Boolean。 |
| Boolean | 将值强制转换为 Boolean。 |
强制转换规则：
**强制转换为 decimal**
| 参数类型 | 结果 |
| --- | --- |
| Int | 没有小数点的 Decimal。 |
| Decimal | 源值。 对于 SQL V2（2016-03-23），整数数字值，例如 `10.0`，将返回一个 `Int` 值 (`10`)，而不是预期的 `Decimal` 值 (`10.0`)。若要可靠地将整数数值转换为 `Decimal` 值，请使用 SQL V1（2015-10-08）作为规则查询语句。 |
| Boolean | true = 1.0，false = 0.0。 |
| String | 尝试将字符串解析为 Decimal。 Amazon IoT 会尝试解析与正则表达式相匹配的字符串：^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1。可自动转换为小数的字符串示例包括“0”、“-1.2”、“5E-12”。 |
| 数组 | Undefined. |
| 对象 | Undefined. |
| Null | Undefined. |
| 未定义 | Undefined. |
**强制转换为 int**
| 参数类型 | 结果 |
| --- | --- |
| Int | 源值。 |
| Decimal | 源值，向下舍入到最近的 Int。 |
| Boolean | true = 1.0，false = 0.0。 |
| String | 尝试将字符串解析为 Decimal。 Amazon IoT 会尝试解析与正则表达式相匹配的字符串：^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1。可自动转换为小数的字符串示例包括“0”、“-1.2”、“5E-12”。 Amazon IoT 尝试将字符串转换为 Decimal，然后向下舍入到最近的 Int。 |
| 数组 | Undefined. |
| 对象 | Undefined. |
| Null | Undefined. |
| 未定义 | Undefined. |
**强制转换为 `Boolean`**
| 参数类型 | 结果 |
| --- | --- |
| Int | 0 = False，任何非零值 = True。 |
| Decimal | 0 = False，任何非零值 = True。 |
| Boolean | 源值。 |
| String | “true” = True 和“false” = False（不区分大小写）。其它字符串值 = Undefined。 |
| 数组 | Undefined. |
| 对象 | Undefined. |
| Null | Undefined. |
| 未定义 | Undefined. |
**强制转换为 string**
| 参数类型 | 结果 |
| --- | --- |
| Int | 标准表示法中 Int 的字符串表示形式。 |
| Decimal | 科学表示法中 Decimal 值的字符串表示。 |
| Boolean | “true”或“false”，全小写。 |
| String | 源值。 |
| 数组 | 数组序列化为 JSON。结果字符串为逗号分隔的列表，括在方括号中。 String 带引号。 Decimal、Int 和 Boolean 不带引号。 |
| 对象 | 序列化为 JSON 的对象。JSON 字符串为键值对的逗号分隔列表，以大括号开头和结束。String 带引号。Decimal、Int、Boolean 和 Null 不带引号。 |
| Null | Undefined. |
| 未定义 | Undefined. |
## ceil(Decimal)
将给定的 `Decimal` 向上舍入到最近的 `Int`。SQL 版本 2015-10-08 及更高版本支持。
示例：
`ceil(1.2)` = 2
`ceil(-1.2)` = -1
****
| 参数类型 | 结果 |
| --- | --- |
| Int | Int，参数值。 |
| Decimal | Int，Decimal 值向上舍入到最近的 Int。 |
| String | Int。字符串将转换为 Decimal 并向上舍入到最近的 Int。如果字符串无法转换为 Decimal，则结果为 Undefined。 |
| 其它值 | Undefined. |
## chr(String)
返回给定 `Int` 参数对应的 ASCII 字符。SQL 版本 2015-10-08 及更高版本支持。
示例：
`chr(65)` = “A”。
`chr(49)` = "1"。
****
| 参数类型 | 结果 |
| --- | --- |
| Int | 与指定的 ASCII 值对应的字符。如果参数不是有效的 ASCII 值，则结果为 Undefined。 |
| Decimal | 与指定的 ASCII 值对应的字符。Decimal 参数会向下舍入至最近的 Int。如果参数不是有效的 ASCII 值，则结果为 Undefined。 |
| Boolean | Undefined. |
| String | 如果 String 可以转换为 Decimal，则向下舍入到最近的 Int。如果参数不是有效的 ASCII 值，则结果为 Undefined。 |
| 数组 | Undefined. |
| 对象 | Undefined. |
| Null | Undefined. |
| 其它值 | Undefined. |
## clientid()
返回发送消息的 MQTT 客户端的 ID，如果未通过 MQTT 发送消息，则返回 `n/a`。SQL 版本 2015-10-08 及更高版本支持。
示例：
`clientid() ` = "123456789012"
## concat()
联接数组或字符串。该函数可接受任意数量的参数，并返回 `String` 或 `Array`。SQL 版本 2015-10-08 及更高版本支持。
示例：
`concat() ` = `Undefined`.
`concat(1) ` = "1"。
`concat([1, 2, 3], 4)` = [1, 2, 3, 4]。
`concat([1, 2, 3], "hello")` = [1, 2, 3, "hello"]
`concat("con", "cat")` = “concat”
`concat(1, "hello")` = “1hello”
`concat("he","is","man")` = “heisman”
`concat([1, 2, 3], "hello", [4, 5, 6])` = [1, 2, 3,“hello”, 4, 5, 6]
****
| 参数数量 | 结果 |
| --- | --- |
| 0 | Undefined. |
| 1 | 不经修改返回参数。 |
| 2\$1 | 如果任意参数为 `Array`，那么结果为包含所有参数的一个数组。如果没有参数为数组，并且至少有一个参数为 `String`，则结果是所有参数的 `String` 表示的联接。参数将使用上文列出的标准转换来转换为字符串。 |
## cos(Decimal)
以弧度为单位返回数字的余弦值。在代入函数之前，`Decimal` 参数舍入到双精度。SQL 版本 2015-10-08 及更高版本支持。
示例：
`cos(0)` = 1。
****
| 参数类型 | 结果 |
| --- | --- |
| Int | Decimal (双精度)，参数的余弦值。虚数结果返回 Undefined。 |
| Decimal | Decimal (双精度)，参数的余弦值。虚数结果返回 Undefined。 |
| Boolean | Undefined. |
| String | Decimal (双精度)，参数的余弦值。如果字符串无法转换为 Decimal，则结果为 Undefined。虚数结果返回 Undefined。 |
| 数组 | Undefined. |
| 对象 | Undefined. |
| Null | Undefined. |
| 未定义 | Undefined. |
## cosh(Decimal)
以弧度为单位返回数字的双曲余弦值。在代入函数之前，`Decimal` 参数舍入到双精度。SQL 版本 2015-10-08 及更高版本支持。
示例：`cosh(2.3)` = 5.037220649268761。
****
| 参数类型 | 结果 |
| --- | --- |
| Int | Decimal (双精度)，参数的双曲余弦值。虚数结果返回 Undefined。 |
| Decimal | Decimal (双精度)，参数的双曲余弦值。虚数结果返回 Undefined。 |
| Boolean | Undefined. |
| String | Decimal (双精度)，参数的双曲余弦值。如果字符串无法转换为 Decimal，则结果为 Undefined。虚数结果返回 Undefined。 |
| 数组 | Undefined. |
| 对象 | Undefined. |
| Null | Undefined. |
| 未定义 | Undefined. |
## 解码（值，decodingScheme）
使用 `decode` 函数来解码一个编码的值。如果解码字符串为 JSON 文档，则返回可寻址对象。否则，解码字符串会返回为字符串。如果字符串无法解码，则函数返回 NULL。此函数支持解码 base64 编码的字符串和协议缓冲区（protobuf）消息格式。
SQL 版本 2016-03-23 及更高版本支持。
值
字符串值或任何有效的表达式，如 [Amazon IoT SQL 参考](iot-sql-reference.md) 中所定义，将返回一个字符串。
decodingScheme
表示用于解码值的方案的文字字符串。目前，只支持 `'base64'` 和 `'proto'`。
### 解码 base64 编码字符串
在此示例中，消息有效载荷包含一个编码值。
```
{
encoded_temp: "eyAidGVtcGVyYXR1cmUiOiAzMyB9Cg=="
}
```
此 SQL 语句中的 `decode` 函数解码消息有效载荷中的值。
```
SELECT decode(encoded_temp,"base64").temperature AS temp from 'topic/subtopic'
```
解码 `encoded_temp` 值会生成以下有效的 JSON 文档，该文档允许 SELECT 语句读取温度值。
```
{ "temperature": 33 }
```
此处显示了此示例中 SELECT 语句的结果。
```
{ "temp": 33 }
```
如果解码的值不是有效的 JSON 文档，则解码的值将作为字符串返回。
### 解码 protobuf 消息有效载荷
您可以使用解码 SQL 函数来配置可以解码 protobuf 消息有效载荷的规则。有关更多信息，请参阅[解码 protobuf 消息有效载荷](binary-payloads.md#binary-payloads-protobuf)。
**重要**
如果您在为 Amazon IoT 委托人设置权限`source‐account`时省略了`source‐arn`或，则任何人 Amazon Web Services 账户 都可以通过其他 Amazon IoT 规则调用您的 Decode 函数。要保护您的函数，请参阅*《Amazon Simple Storage Service 用户指南》*中的[存储桶策略](https://docs.amazonaws.cn/AmazonS3/latest/userguide/bucket-policies.html)。
此函数签名类似以下内容：
```
decode(, 'proto', '', '', '', '')
```
`ENCODED DATA`
指定要解码的 protobuf 编码数据。如果发送到规则的整个消息都是 protobuf 编码的数据，则可以使用 `*` 引用原始二进制传入有效载荷。否则，此字段必须是 base-64 编码的 JSON 字符串，并且可以直接传入对该字符串的引用。
1) 要解码原始二进制 protobuf 传入有效载荷，请执行以下操作：
```
decode(*, 'proto', ...)
```
2) 要解码由 base64 编码的字符串 'a.b' 表示的 protobuf 编码的消息，请执行以下操作：
```
decode(a.b, 'proto', ...)
```
`proto`
以 protobuf 消息格式指定要解码的数据。如果您指定 `base64` 而不是 `proto`，此函数会将 base64 编码的字符串解码为 JSON。
`S3 BUCKET NAME`
您上传 `FileDescriptorSet` 文件的 Amazon S3 存储桶的名称。
`S3 OBJECT KEY`
指定 Amazon S3 存储桶中 `FileDescriptorSet` 文件的对象键。
`PROTO NAME`
生成 `FileDescriptorSet` 文件的 `.proto` 文件名（不包括扩展名）。
`MESSAGE TYPE`
`FileDescriptorSet` 文件中 protobuf 消息结构的名称，要解码的数据应符合该结构。
使用解码 SQL函数的示例 SQL 表达式可能如下所示：
```
SELECT VALUE decode(*, 'proto', 's3-bucket', 'messageformat.desc', 'myproto', 'messagetype') FROM 'some/topic'
```
+ `*`
表示二进制传入有效载荷，它符合名为 `mymessagetype` 的 protobuf 消息类型。
+ `messageformat.desc`
`FileDescriptorSet` 文件存储在名为 `s3-bucket` 的 Amazon S3 存储桶中。
+ `myproto`
用于生成名为 `myproto.proto` 的 `FileDescriptorSet` 文件的原始 `.proto` 文件。
+ `messagetype`
`myproto.proto` 中定义的名为 `messagetype` 的消息类型（以及任何导入的依赖项）。
## encode(value, encodingScheme)
根据编码方案，使用 `encode` 函数将有效载荷（可能是非 JSON 数据）编码为字符串表示形式。SQL 版本 2016-03-23 及更高版本支持。
值
[Amazon IoT SQL 参考](iot-sql-reference.md) 中所定义的任何有效的表达式。您可以指定 \$1 以对整个有效载荷进行编码，无论它是否为 JSON 格式。如果您提供了表达式，评估的结果将在编码之前转换为字符串。
encodingScheme
代表您要使用的编码方案的文字字符串。目前仅支持 `'base64'`。
## endswith(String, String)
返回 `Boolean` 来表示第一个 `String` 参数是否以第二个 `String` 参数结尾。如果任一参数为 `Null` 或 `Undefined`，则结果为 `Undefined`。SQL 版本 2015-10-08 及更高版本支持。
示例：`endswith("cat","at")` = true。
****
| 参数类型 1 | 参数类型 2 | 结果 |
| --- | --- | --- |
| String | String | 如果第一个参数以第二个参数结尾，则为 true。否则为 false。 |
| 其它值 | 其它值 | 两个参数都使用标准转换规则转换为字符串。如果第一个参数以第二个参数结尾，则为 true。否则为 false。如果任一参数为 Null 或 Undefined，则结果为 Undefined。 |
## exp(Decimal)
返回 e 的 `Decimal` 参数次方。在代入函数之前，`Decimal` 参数舍入到双精度。SQL 版本 2015-10-08 及更高版本支持。
示例：`exp(1)` = e。
****
| 参数类型 | 结果 |
| --- | --- |
| Int | Decimal (双精度)，e ^ 参数。 |
| Decimal | Decimal (双精度)，e ^ 参数。 |
| String | Decimal (双精度)，e ^ 参数。如果 String 无法转换为 Decimal，则结果为 Undefined。 |
| 其它值 | Undefined. |
## floor(Decimal)
将给定的 `Decimal` 向下舍入到最接近的 `Int`。SQL 版本 2015-10-08 及更高版本支持。
示例：
`floor(1.2)` = 1
`floor(-1.2)` = -2
****
| 参数类型 | 结果 |
| --- | --- |
| Int | Int，参数值。 |
| Decimal | Int，Decimal 值会向下舍入至最接近的 Int。 |
| String | Int。字符串将转换为 Decimal 并向下舍入到最接近的 Int。如果字符串无法转换为 Decimal，则结果为 Undefined。 |
| 其它值 | Undefined. |
## 入
从一个集合数据类型（数组、字符串、对象）中提取值。第一个参数不会进行任何转换。根据表中的记载对第二个参数进行转换。SQL 版本 2015-10-08 及更高版本支持。
示例：
`get(["a", "b", "c"], 1) ` = "b"
`get({"a":"b"}, "a")` = "b"
`get("abc", 0)` = “a”
****
| 参数类型 1 | 参数类型 2 | 结果 |
| --- | --- | --- |
| 数组 | 任何类型 (转换为 Int) | 在第二个参数（已经转换为 Array）提供的 Int 中，从零开始索引得到的项目。如果转换已不成功，结果为 Undefined。如果索引超出 Array 的范围（负值或大于等于数组长度），则结果为 Undefined。 |
| 字符串 | 任何类型 (转换为 Int) | 在第二个参数（已经转换为 Int）提供的字符串中，从零开始索引得到的字符。如果转换已不成功，结果为 Undefined。如果索引超出字符串的范围（负值或大于等于字符串长度），则结果为 Undefined。 |
| 对象 | String（不进行转换） | 第一个参数对象中存储的值与作为第二个参数提供的字符串键相对应。 |
| 其它值 | 任意值 | Undefined. |
## get\$1dynamodb（tableName、、、、、roLearn partitionKeyName） partitionKeyValue sortKeyName sortKeyValue
从 DynamoDB 表中检索数据。`get_dynamodb()` 可让您在计算规则时查询 DynamoDB 表。您可以使用从 DynamoDB 中检索到的数据筛选或增加消息有效载荷。SQL 版本 2016-03-23 及更高版本支持。
`get_dynamodb()` 接受以下参数：
tableName
要查询的 DynamoDB 表的名称。
partitionKeyName
分区键的名称。有关更多信息，请参阅 [DynamoDB Keys](https://docs.amazonaws.cn/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey)。
partitionKeyValue
用于标识记录的分区键的值。有关更多信息，请参阅 [DynamoDB Keys](https://docs.amazonaws.cn/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey)。
sortKeyName
（可选）排序键的名称。仅当查询的 DynamoDB 表使用复合键时需要此参数。有关更多信息，请参阅 [DynamoDB Keys](https://docs.amazonaws.cn/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey)。
sortKeyValue
（可选）排序键的值。仅当查询的 DynamoDB 表使用复合键时需要此参数。有关更多信息，请参阅 [DynamoDB Keys](https://docs.amazonaws.cn/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey)。
roleArn
授予对 DynamoDB 表的访问权限的 IAM 角色的 ARN。规则引擎将承担此角色以代表您访问 DynamoDB 表。避免使用过于宽容的角色。仅向角色授予规则所需的那些权限。以下是授予对一个 DynamoDB 表的访问权限的示例策略。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "dynamodb:GetItem",
"Resource": "arn:aws:dynamodb:us-east-1:123456789012:table/table-name"
}
]
}
```
举例说明您如何使用 `get_dynamodb()`，例如您有一个 DynamoDB 表，其中包含连接到 Amazon IoT的所有设备的设备 ID 和位置信息。以下 SELECT 语句使用 `get_dynamodb()` 函数检索指定的设备 ID 的位置：
`SELECT *, get_dynamodb("InServiceDevices", "deviceId", id, "arn:aws:iam::12345678910:role/getdynamo").location AS location FROM 'some/topic' `
**注意**
每个 SQL 语句最多可以调用 `get_dynamodb()` 一次。在单个 SQL 语句中调用 `get_dynamodb()` 多次会导致规则在不调用任何操作的情况下终止。
## get\$1mqtt\$1property(name)
引用以下任何 MQTT5 标题：`contentType``payLoadFormatIndicator`、`responseTopic`、和`correlationData`。此函数将以下任何文字字符串作为参数：`content_type`、`format_indicator`、`response_topic` 和 `correlation_data`。有关更多信息，请参阅以下**函数参数**表。
contentType
字符串：一个 UTF-8 编码的字符串，用于描述发布消息的内容。
payLoadFormat指示器
字符串：一个枚举字符串值，指示有效载荷是否格式化为 UTF-8。有效值为 `UNSPECIFIED_BYTES` 和 `UTF8_DATA`。
responseTopic
字符串：一个 UTF-8 编码的字符串，用作响应消息的主题名称。响应主题用于描述接收方应作为请求/响应流程的一部分发布到的主题。主题不得包含通配符。
correlationData
字符串：请求消息的发送方使用 base64 编码的二进制数据来识别收到响应消息时响应消息的请求。
下表显示了可接受的函数参数，及其与 `get_mqtt_property` 函数相关的返回类型：
**函数参数**
| SQL | 返回的数据类型（如果存在） | 返回的数据类型（如果不存在） |
| --- | --- | --- |
| get\$1mqtt\$1property("format\$1indicator") | 字符串（未指定 \$1BYTES 或 \$1DATA） UTF8 | 字符串（UNSPECIFIED\$1BYTES） |
| get\$1mqtt\$1property("content\$1type") | 字符串 | 未定义 |
| get\$1mqtt\$1property("response\$1topic") | 字符串 | 未定义 |
| get\$1mqtt\$1property("correlation\$1data") | base64 编码的字符串 | 未定义 |
| get\$1mqtt\$1property("some\$1invalid\$1name") | 未定义 | 未定义 |
以下示例 Rules SQL 引用了以下任何 MQTT5 标头：`contentType``payLoadFormatIndicator``responseTopic`、、和`correlationData`。
```
SELECT *, get_mqtt_property('content_type') as contentType,
get_mqtt_property('format_indicator') as payloadFormatIndicator,
get_mqtt_property('response_topic') as responseTopic,
get_mqtt_property('correlation_data') as correlationData
FROM 'some/topic'
```
## get\$1or\$1default（表达式，默认值）
如果已指定，则返回第二个参数中的默认值，否则在第一个参数中的表达式返回 null、undefined 或失败时返回 undefined。SQL 版本 2016-03-23 及更高版本支持。
**重要**
`get_or_default`不直接支持非 JSON 有效负载。如果您使用的是非 JSON 负载，请使用`encode`或`decode`函数。
`get_or_default()` 接受以下参数：
expression
任何包含[数据类型](iot-sql-data-types.md)、、[函数](#iot-sql-functions)、[变量[文本](iot-sql-literals.md)](iot-sql-set.md#iot-sql-set-usage)[嵌套对象查询](iot-sql-nested-queries.md)、或的有效表达式[JSON 扩展](iot-sql-json.md)。
defaultValue
（可选）任何包含[数据类型](iot-sql-data-types.md)、、[函数](#iot-sql-functions)、[变量[文本](iot-sql-literals.md)](iot-sql-set.md#iot-sql-set-usage)[嵌套对象查询](iot-sql-nested-queries.md)、或的有效表达式[JSON 扩展](iot-sql-json.md)。这是第一个参数返回 null、undefined 或失败时要返回的值。
默认值参数不允许使用从客户拥有的资源（例如 get\$1secret、get\$1dynamodb、aws\$1lambda、get\$1thing\$1shadow、decode-protobuf 和 machineLearning\$1predict）中获取数据的函数。
下表显示了每个参数的可接受函数参数及其相关输出：
| 第一个论点 | 第二个论点 | Output |
| --- | --- | --- |
| 成功评估 | 任何值或未指定 | 第一个参数值。 |
| 未定义、空或失败 | 任何值，包括 “未定义” 或 “空” | 第二个参数值。 |
| 未定义、空或失败 | 未指定 | Undefined |
**示例：**
示例 1：
以下示例提供了 DynamoDB 表或查询失败时的默认值：
```
SELECT
device_id,
get_or_default(
get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME"),
{"mode": "standard", "timeout": 30, "enabled": true }
) as config
FROM 'device/telemetry'
```
示例 2：
如果状态未定义，则以下示例提供了安全的默认值 “UNKNOWN”：
```
SELECT
get_or_default( CASE status
WHEN 'active' THEN 'GOOD'
WHEN 'inactive' THEN 'BAD'/
ELSE 'UNKNOWN'
END, 'UNKNOWN') as status_category
FROM 'topic/subtopic'
```
示例 3：
以下示例显示了如何使用带有单个参数的 get\$1or\$1default。这在您可能没有明确的默认值但又不希望规则执行失败的情况下很有用。
```
SELECT
get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME") as config
FROM 'device/telemetry'
```
如果 DynamoDB 查找失败，则规则执行将失败，并且不会执行任何操作。如果改用以下 SQL：
```
SELECT
get_or_default(get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME")) as config
FROM 'device/telemetry'
```
get\$1or\$1default 语句的计算结果将为`Undefined`，因此在本示例中，SELECT 语句的总体计算结果将为，`{}`并且将尝试执行任何规则操作。
**重要**
我们建议在使用此功能时遵循以下最佳实践来维护安全性：
避免在规则定义中使用硬编码的密码，包括默认值
Amazon Secrets Manager 用于管理敏感信息
## get\$1registry\$1data（RegistryAPI、ThingName、roLearn）
检索 Amazon IoT 规则中的 Amazon IoT 事物注册表数据。您可以读取注册表数据（例如属性、事物类型和设备所属的事物组），并使用这些信息来筛选、丰富或动态路由消息。SQL 版本 2016-03-23 及更高版本支持。
`get_registry_data()` 接受以下参数：
注册表 API
正在调用的注册表 API。有效值为 `DescribeThing` 和 `ListThingGroupsForThing`。这些值必须是常量字符串。
thingName
字符串：要检索其注册表数据的事物的名称。
roleArn
字符串：根据所调用的 API 具有`iot:DescribeThing` and/or `iot:ListThingGroupsForThing`权限的角色 ARN。
该`get_registry_data`函数的响应格式与调用的注册表 API 相同。有关更多信息，请参阅 [DescribeThing](https://docs.amazonaws.cn//iot/latest/apireference/API_DescribeThing.html) 和 [ListThingGroupsForThing](https://docs.amazonaws.cn//iot/latest/apireference/API_ListThingGroupsForThing.html) APIs。
示例：
您可以检索事物类型信息，以便筛选事物类型所在的事物（事物名称与 MQTT 客户端 ID 匹配）的 Amazon IoT Core 生命周期事件消息。`testenv`
```
SELECT *
FROM '$aws/events/lifecycle/+'
WHERE
get_registry_data("DescribeThing",clientId,[roleArn]).thingTypeName='testenv'
```
示例：
您可以使用网关设备发送的所有消息的事`sensor1`物名称检索设备的事物属性`gateway1`。
```
SELECT *, get_registry_data("DescribeThing","sensor1",[roleArn]).attributes.temperature_threhold AS device1_tempthreshold
FROM home1/gateway1/sensor1/#
```
**注意**
每条 SQL 语句最多可以调用`get_registry_data()`一次，操作和错误操作的替换模板只能调用一次。
## get\$1secret(secretId, secretType, key, roleArn)
在 [Amazon Secrets Manager](https://docs.amazonaws.cn/secretsmanager/latest/userguide/) 中检索密钥当前版本的加密 `SecretString` 或者 `SecretBinary` 字段中的值。有关创建和维护密钥的更多信息，请参阅[CreateSecret[UpdateSecret](https://docs.amazonaws.cn/secretsmanager/latest/apireference/API_UpdateSecret.html)](https://docs.amazonaws.cn/secretsmanager/latest/apireference/API_CreateSecret.html)、和[PutSecretValue](https://docs.amazonaws.cn/secretsmanager/latest/apireference/API_PutSecretValue.html)。
`get_secret()` 接受以下参数：
secretId
字符串：要检索的密钥的 Amazon 资源名称（ARN）或友好名称。
secretType
字符串：密钥类型。有效值：`SecretString` \$1 `SecretBinary`。
SecretString
+ 对于您使用 APIs、或 Amazon Secrets Manager 控制台创建为 JSON 对象的密钥： Amazon CLI
+ 如果为 `key` 参数指定值，则函数返回指定键的值。
+ 如果您没有为 `key` 参数指定值，则函数将返回整个 JSON 对象。
+ 对于您使用 APIs 或作为非 JSON 对象创建的机密： Amazon CLI
+ 如果为 `key` 参数指定值，则函数失败并出现异常。
+ 如果您没有为 `key` 参数指定值，则函数返回密钥的内容。
SecretBinary
+ 如果为 `key` 参数指定值，则函数失败并出现异常。
+ 如果您没有为 `key` 参数指定值，则函数将密钥值作为 base64 编码 UTF-8 字符串返回。
键
（可选）字符串：存储在密钥的 `SecretString` 字段中的 JSON 对象里的键名称。如果您希望仅检索存储在密钥中而不是整个 JSON 对象中的键值，请使用此值。
如果您为此参数指定了一个值，而密钥的 `SecretString` 字段中不包含 JSON 对象，此函数将失败并出现异常。
roleArn
String：具有 `secretsmanager:GetSecretValue` 和 `secretsmanager:DescribeSecret` 权限的角色 ARN。
**注意**
此函数始终返回密钥的当前版本（带有 `AWSCURRENT` 标签的版本）。 Amazon IoT 规则引擎将每个密钥缓存最多 15 分钟。因此，规则引擎最多可能需要 15 分钟才能更新密钥。这意味着，如果您在更新后最多 15 分钟内检索到密钥 Amazon Secrets Manager，则此函数可能会返回之前的版本。
此功能不是按流量计费的，但会 Amazon Secrets Manager 收费。由于密钥缓存机制，规则引擎偶尔会调用 Amazon Secrets Manager。由于规则引擎是完全分布的服务，因此您可能会在 15 分钟缓存窗口期间看到规则引擎中的多个 Secrets Manager API 调用。
示例：
您可以在 HTTPS 规则操作中的身份验证标头里使用 `get_secret` 函数，如下面的 API 密钥身份验证示例所示。
```
"API_KEY": "${get_secret('API_KEY', 'SecretString', 'API_KEY_VALUE', 'arn:aws:iam::12345678910:role/getsecret')}"
```
有关 HTTPS 规则操作的更多信息，请参阅 [HTTP](https-rule-action.md)。
## get\$1thing\$1shadow（thingName、shadowName、roLearn）
返回指定事物的指定影子。SQL 版本 2016-03-23 及更高版本支持。
thingName
String：您要检索其影子的事物的名称。
shadowName
（可选）字符串：影子的名称。只有在引用命名的影子时，才需要使用该参数。
roleArn
String：具有 `iot:GetThingShadow` 的 ARN 角色。
示例：
与命名的影子一起使用时，请提供 `shadowName` 参数。
```
SELECT * from 'topic/subtopic'
WHERE
get_thing_shadow("MyThing","MyThingShadow","arn:aws:iam::123456789012:role/AllowsThingShadowAccess")
.state.reported.alarm = 'ON'
```
与未命名的影子一起使用时，请省略 `shadowName` 参数。
```
SELECT * from 'topic/subtopic'
WHERE
get_thing_shadow("MyThing","arn:aws:iam::123456789012:role/AllowsThingShadowAccess")
.state.reported.alarm = 'ON'
```
## get\$1user\$1properties () userPropertyKey
引用用户属性，这是中支持的一种属性标题 MQTT5。
userProperty
字符串：用户属性是一个键-值对。此函数将键作为参数，并返回与关联的键匹配的所有值的数组。
**函数参数**
对于邮件标题中的以下用户属性：
| 键 | 值 |
| --- | --- |
| 某个键 | 某个值 |
| 其他键 | 其他值 |
| 某个键 | 带有重复键的值 |
下表显示了预期的 SQL 行为：
| SQL | 返回的数据类型 | 返回的数据值 |
| --- | --- | --- |
| get\$1user\$1properties('some key') | 字符串数组 | ['some value', 'value with duplicate key'] |
| get\$1user\$1properties('other key') | 字符串数组 | ['a different value'] |
| get\$1user\$1properties( ) | 键值对对象的数组 | [\$1'"some key": "some value"'\$1, \$1"other key": "a different value"\$1, \$1"some key": "value with duplicate key"\$1] |
| get\$1user\$1properties('non-existent key') | 未定义 | |
以下示例 Rules SQL 将用户属性（一种 MQTT5属性标头）引用到有效载荷中：
```
SELECT *, get_user_properties('user defined property key') as userProperty
FROM 'some/topic'
```
## 哈希函数
Amazon IoT 提供以下哈希函数：
+ md2
+ md5
+ sha1
+ sha224
+ sha256
+ sha384
+ sha512
所有哈希函数都可以输入一个字符串参数。结果为该字符串的哈希值。对非字符串参数进行标准字符串转换。所有哈希函数在 SQL 版本 2015-10-08 及更高版本中均受支持。
示例：
`md2("hello")` = “a9046c73e00331af68917d3804f70655”
`md5("hello")` = “5d41402abc4b2a76b9719d911017c592”
## indexof(String, String)
返回第二个参数的第一个索引（从零开始）作为第一个参数的子字符串。两个参数均为字符串。如果参数数据类型不是字符串，则应用标准字符串转换规则进行转换。此函数只对字符串有效，不适用于数组。SQL 版本 2016-03-23 及更高版本支持。
示例：
`indexof("abcd", "bc") ` = 1
## isNull()
如果参数为 `Null` 值，则返回 true。SQL 版本 2016-03-23 及更高版本支持。
示例：
`isNull(5) ` = false。
`isNull(Null) ` = true。
****
| 参数类型 | 结果 |
| --- | --- |
| Int | false |
| Decimal | false |
| Boolean | false |
| String | false |
| Array | false |
| Object | false |
| Null | true |
| Undefined | false |
## isUndefined()
如果参数为 `Undefined`，则返回 true。SQL 版本 2016-03-23 及更高版本支持。
示例：
`isUndefined(5) ` = false。
`isUndefined(floor([1,2,3]))) ` = true。
****
| 参数类型 | 结果 |
| --- | --- |
| Int | false |
| Decimal | false |
| Boolean | false |
| String | false |
| Array | false |
| Object | false |
| Null | false |
| Undefined | true |
## length(String)
返回输入字符数中的字符数。对非 `String` 参数应用标准转换规则。SQL 版本 2016-03-23 及更高版本支持。
示例：
`length("hi")` = 2
`length(false)` = 5
## ln(Decimal)
返回参数的自然对数。在代入函数之前，`Decimal` 参数舍入到双精度。SQL 版本 2015-10-08 及更高版本支持。
示例：`ln(e)` = 1。
****
| 参数类型 | 结果 |
| --- | --- |
| Int | Decimal (双精度)，参数的自然对数。 |
| Decimal | Decimal (双精度)，参数的自然对数。 |
| Boolean | Undefined. |
| String | Decimal (双精度)，参数的自然对数。如果字符串无法转换为 Decimal，则结果为 Undefined。 |
| 数组 | Undefined. |
| 对象 | Undefined. |
| Null | Undefined. |
| 未定义 | Undefined. |
## log(Decimal)
返回参数的以 10 为底的对数。在代入函数之前，`Decimal` 参数舍入到双精度。SQL 版本 2015-10-08 及更高版本支持。
示例：`log(100)` = 2.0。
****
| 参数类型 | 结果 |
| --- | --- |
| Int | Decimal (双精度)，参数以 10 为底的对数。 |
| Decimal | Decimal (双精度)，参数以 10 为底的对数。 |
| Boolean | Undefined. |
| String | Decimal (双精度)，参数以 10 为底的对数。如果 String 无法转换为 Decimal，则结果为 Undefined。 |
| 数组 | Undefined. |
| 对象 | Undefined. |
| Null | Undefined. |
| 未定义 | Undefined. |
## lower(String)
返回给定 `String` 的小写版本。非字符串参数使用标准转换规则转换为字符串。SQL 版本 2015-10-08 及更高版本支持。
示例：
`lower("HELLO")` = “hello”。
`lower(["HELLO"])` = “[\$1“hello\$1”]”。
## lpad(String, Int)
返回 `String` 参数，在输入参数的左侧填充由第二个参数指定的数量的空格。`Int` 参数必须介于 0 到 1000 之间。如果提供的值在这一有效范围之外，则参数被设置为与其最近的值（0 或 1000）。SQL 版本 2015-10-08 及更高版本支持。
示例：
`lpad("hello", 2)` = "` hello`".
`lpad(1, 3)` = "` 1`"
****
| 参数类型 1 | 参数类型 2 | 结果 |
| --- | --- | --- |
| String | Int | String，在输入 String 左侧填充由 Int 指定的数量的空格。 |
| String | Decimal | Decimal 参数向下舍入到最近的 Int，并在 String 左侧填充指定数量的空格。 |
| String | String | 第二个参数被转换为 Decimal，向下舍入到最近的 Int，并在 String 左侧填充指定数量的空格。如果第二个参数无法转换为 Int，则结果为 Undefined。 |
| 其它值 | Int/Decimal/String | 第一个值使用标准转换规则转换为 String，然后对该 String 应用 LPAD 函数。如果它无法转换，则结果为 Undefined。 |
| 任意值 | 其它值 | Undefined. |
## ltrim(String)
从提供的 `String` 中删除所有前导空白（制表符和空格）。SQL 版本 2015-10-08 及更高版本支持。
示例：
`Ltrim(" h i ")` = “hi”。
****
| 参数类型 | 结果 |
| --- | --- |
| Int | 删除了所有前导空白的 Int 的 String 表示形式。 |
| Decimal | 删除了所有前导空白的 Decimal 的 String 表示形式。 |
| Boolean | 布尔值（“true”或“false”）在删除所有前导空格之后的 String 表示形式。 |
| String | 删除所有前导空白之后的参数。 |
| 数组 | Array（使用标准转换规则）在删除所有前导空白之后的 String 表示形式。 |
| 对象 | 对象（使用标准转换规则）在删除所有前导空白之后的 String 表示形式。 |
| Null | Undefined. |
| 未定义 | Undefined. |
## machinelearning\$1predict(modelId, roleArn, record)
使用该`machinelearning_predict`函数使用基于 Amazon A SageMaker I 模型的 MQTT 消息中的数据进行预测。SQL 版本 2015-10-08 及更高版本支持。`machinelearning_predict` 函数的参数如下：
modelId
对其运行预测的模型的 ID。必须启用模型的实时端点。
roleArn
IAM 角色，拥有具备 `machinelearning:Predict` 和 `machinelearning:GetMLModel` 权限的策略并允许访问运行预测所针对的模型。
记录
要传递到 SageMaker AI 预测 API 的数据。该参数应表示为单层 JSON 对象。如果记录是多级 JSON 对象，该记录将通过序列化其值来进行平展。例如，以下 JSON：
```
{ "key1": {"innerKey1": "value1"}, "key2": 0}
```
会变为：
```
{ "key1": "{\"innerKey1\": \"value1\"}", "key2": 0}
```
该函数返回具有以下字段的 JSON 对象：
predictedLabel
基于模型的输入分类。
details
包含以下属性：
PredictiveModelType
模型类型。有效值为 REGRESSION、BINARY、MULTICLASS。
算法
SageMaker 人工智能用来进行预测的算法。该值必须为 SGD。
predictedScores
包含与每个标签对应的原始分类分数。
predictedValue
SageMaker 人工智能预测的价值。
## mod(Decimal, Decimal)
返回第一个参数除以第二个参数的余数。等效于 [remainder(Decimal, Decimal)](#iot-func-remainder)。您还可以使用“%”作为相同取模功能的插入运算符。SQL 版本 2015-10-08 及更高版本支持。
示例：`mod(8, 3)` = 2。
****
| 左侧操作数 | 右侧操作数 | Output |
| --- | --- | --- |
| Int | Int | Int，第一个参数对第二个参数取模。 |
| Int/Decimal | Int/Decimal | Decimal，第一个参数对第二个操作数取模。 |
| String/Int/Decimal | String/Int/Decimal | 如果所有字符串转换为小数，则结果为第一个参数对第二个参数取模的值。否则为 Undefined。 |
| 其它值 | 其它值 | Undefined. |
## nanvl (AnyValue,) AnyValue
如果第一个参数为有效的 `Decimal`，则返回第一个参数。否则，返回第二个参数。SQL 版本 2015-10-08 及更高版本支持。
示例：`Nanvl(8, 3)` = 8。
****
| 参数类型 1 | 参数类型 2 | Output |
| --- | --- | --- |
| 未定义 | 任意值 | 第二个参数。 |
| Null | 任意值 | 第二个参数。 |
| Decimal (NaN) | 任意值 | 第二个参数。 |
| Decimal（非 NaN） | 任意值 | 第一个参数。 |
| 其它值 | 任意值 | 第一个参数。 |
## newuuid()
返回随机的 16 字节 UUID。SQL 版本 2015-10-08 及更高版本支持。
示例：`newuuid()` = `123a4567-b89c-12d3-e456-789012345000`
## numbytes(String)
返回输入字符串 UTF-8 编码中的字节数。对非 `String` 参数应用标准转换规则。SQL 版本 2016-03-23 及更高版本支持。
示例：
`numbytes("hi")` = 2
`numbytes("€") ` = 3
## parse\$1time(String, Long[, String])
使用该`parse_time`函数将时间戳格式化为人类可读 date/time 的格式。SQL 版本 2016-03-23 及更高版本支持。要将时间戳字符串转换为毫秒，请参阅 [time\$1to\$1epoch(String, String)](#iot-sql-function-time-to-epoch)。
`parse_time` 函数采用下列参数：
模式
（字符串）遵循 [Joda-](http://www.joda.org/joda-time/apidocs/org/joda/time/format/DateTimeFormat.html) Time 格式的 date/time 模式。
timestamp
(Long) 要采用自 Unix 纪元时间以来的毫秒数格式表示的时间。请参阅函数 [timestamp()](#iot-function-timestamp)。
timezone
（字符串）采用日期/时间格式的时区。默认值为“UTC”。此函数支持 [Joda-Time 时区](http://joda-time.sourceforge.net/timezones.html)。此参数是可选的。
示例：
在将此消息发布到主题“A/B”时，有效载荷 `{"ts": "1970.01.01 AD at 21:46:40 CST"}` 发送到 S3 存储桶：
```
{
"ruleArn": "arn:aws:iot:us-east-2:ACCOUNT_ID:rule/RULE_NAME",
"topicRulePayload": {
"sql": "SELECT parse_time(\"yyyy.MM.dd G 'at' HH:mm:ss z\", 100000000, 'America/Belize' ) as ts FROM 'A/B'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"s3": {
"roleArn": "arn:aws:iam::ACCOUNT_ID:rule:role/ROLE_NAME",
"bucketName": "BUCKET_NAME",
"key": "KEY_NAME"
}
}
],
"ruleName": "RULE_NAME"
}
}
```
在将此消息发布到主题“A/B”时，与 `{"ts": "2017.06.09 AD at 17:19:46 UTC"}` 类似（但具有当前日期/时间）的有效载荷发送到 S3 存储桶：
```
{
"ruleArn": "arn:aws:iot:us-east-2:ACCOUNT_ID:rule/RULE_NAME",
"topicRulePayload": {
"sql": "SELECT parse_time(\"yyyy.MM.dd G 'at' HH:mm:ss z\", timestamp() ) as ts FROM 'A/B'",
"awsIotSqlVersion": "2016-03-23",
"ruleDisabled": false,
"actions": [
{
"s3": {
"roleArn": "arn:aws:iam::ACCOUNT_ID:rule:role/ROLE_NAME",
"bucketName": "BUCKET_NAME",
"key": "KEY_NAME"
}
}
],
"ruleName": "RULE_NAME"
}
}
```
`parse_time()` 也可用作替换模板。例如，在将此消息发布到主题“A/B”时，有效载荷发送到密钥为“2017”的 S3 存储桶：
```
{
"ruleArn": "arn:aws:iot:us-east-2:ACCOUNT_ID:rule/RULE_NAME",
"topicRulePayload": {
"sql": "SELECT * FROM 'A/B'",
"awsIotSqlVersion": "2016-03-23",
"ruleDisabled": false,
"actions": [{
"s3": {
"roleArn": "arn:aws:iam::ACCOUNT_ID:rule:role/ROLE_NAME",
"bucketName": "BUCKET_NAME",
"key": "${parse_time('yyyy', timestamp(), 'UTC')}"
}
}],
"ruleName": "RULE_NAME"
}
}
```
## power(Decimal, Decimal)
返回第一个参数的第二个参数次幂的值。在代入函数之前，`Decimal` 参数舍入到双精度。SQL 版本 2015-10-08 及更高版本支持。SQL 版本 2015-10-08 及更高版本支持。
示例：`power(2, 5)` = 32.0。
****
| 参数类型 1 | 参数类型 2 | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Decimal (双精度)，返回第一个参数的第二个参数次幂的值。 |
| Int/Decimal/String | Int/Decimal/String | Decimal (双精度)，返回第一个参数的第二个参数次幂的值。所有字符串均转换为小数。如果任何 String 无法转换为 Decimal，则结果为 Undefined。 |
| 其它值 | 其它值 | Undefined. |
## principal()
返回设备用于身份验证的主体，取决于触发消息的发布方式。下表介绍了为每个发布方法和协议返回的主体。
****
| 消息的发布方式 | 协议 | 凭证类型 | Principal |
| --- | --- | --- | --- |
| MQTT 客户端 | MQTT | X.509 设备证书 | X.509 证书指纹 |
| Amazon IoT 控制台 MQTT 客户端 | MQTT | IAM 用户或角色 | iam-role-id:session-name |
| Amazon CLI | HTTP | IAM 用户或角色 | userid |
| Amazon IoT 设备软件开发工具包 | MQTT | X.509 设备证书 | X.509 证书指纹 |
| Amazon IoT 设备软件开发工具包 | MQTT 结束了 WebSocket | IAM 用户或角色 | userid |
下面的示例展示了 `principal()` 能够返回的不同类型的值：
+ X.509 证书指纹：`ba67293af50bf2506f5f93469686da660c7c844e7b3950bfb16813e0d31e9373`
+ IAM 角色 ID 和会话名称：`ABCD1EFG3HIJK2LMNOP5:my-session-name`
+ 返回用户 ID：`ABCD1EFG3HIJK2LMNOP5`
## rand()
返回在 0.0 到 1.0 之间均匀分布的伪随机双精度值。SQL 版本 2015-10-08 及更高版本支持。
示例：
`rand()` = 0.8231909191640703
## regexp\$1matches(String, String)
如果字符串（第一个参数）包含正则表达式（第二个参数）的匹配项，则返回 true。如果您在正则表达式中使用 `|`，请结合使用 `()`。
示例：
`regexp_matches("aaaa", "a{2,}") ` = true。
`regexp_matches("aaaa", "b")` = false。
`regexp_matches("aaa", "(aaa|bbb)") ` = true。
`regexp_matches("bbb", "(aaa|bbb)") ` = true。
`regexp_matches("ccc", "(aaa|bbb)") ` = false。
**第一个参数：**
| 参数类型 | 结果 |
| --- | --- |
| Int | String 的 Int 表示形式。 |
| Decimal | String 的 Decimal 表示形式。 |
| Boolean | 布尔值（“true”或“false”）的 String 表示形式。 |
| String | String。 |
| 数组 | Array (使用标准转换规则) 的 String 表示形式。 |
| 对象 | 对象 (使用标准转换规则) 的 String 表示形式。 |
| Null | Undefined. |
| 未定义 | Undefined. |
*第二个参数：*
必须是有效的正则表达式。非字符串类型使用标准转换规则转换为 `String`。根据类型，生成的字符串可能不是有效的正则表达式。如果（转换后的）参数不是有效的正则表达式，则结果为 `Undefined`。
## regexp\$1replace(String, String, String)
用第三个参数替换在第一个参数中出现的所有第二个参数（正则表达式）。用“\$1”引用捕获组。SQL 版本 2015-10-08 及更高版本支持。
示例：
`regexp_replace("abcd", "bc", "x")` = “axd”。
`regexp_replace("abcd", "b(.*)d", "$1")` = “ac”。
**第一个参数：**
| 参数类型 | 结果 |
| --- | --- |
| Int | String 的 Int 表示形式。 |
| Decimal | String 的 Decimal 表示形式。 |
| Boolean | 布尔值（“true”或“false”）的 String 表示形式。 |
| String | 源值。 |
| 数组 | Array (使用标准转换规则) 的 String 表示形式。 |
| 对象 | 对象 (使用标准转换规则) 的 String 表示形式。 |
| Null | Undefined. |
| 未定义 | Undefined. |
*第二个参数：*
必须是有效的正则表达式。非字符串类型使用标准转换规则转换为 `String`。根据类型，生成的字符串可能不是有效的正则表达式。如果（转换后的）参数不是有效的正则表达式，则结果为 `Undefined`。
*第三个参数：*
必须是有效的正则表达式替代字符串。（可以引用捕获组。） 非字符串类型使用标准转换规则转换为 `String`。如果（转换后的）参数不是有效的正则表达式替代字符串，则结果为 `Undefined`。
## regexp\$1substr(String, String)
在第一个参数中查找第二个参数（正则表达式）的第一个匹配项。用“\$1”引用捕获组。SQL 版本 2015-10-08 及更高版本支持。
示例：
`regexp_substr("hihihello", "hi")` = "hi"
`regexp_substr("hihihello", "(hi)*")` = “hihi”
**第一个参数：**
| 参数类型 | 结果 |
| --- | --- |
| Int | String 的 Int 表示形式。 |
| Decimal | String 的 Decimal 表示形式。 |
| Boolean | 布尔值（“true”或“false”）的 String 表示形式。 |
| String | String 参数。 |
| 数组 | Array (使用标准转换规则) 的 String 表示形式。 |
| 对象 | 对象 (使用标准转换规则) 的 String 表示形式。 |
| Null | Undefined. |
| 未定义 | Undefined. |
*第二个参数：*
必须是有效的正则表达式。非字符串类型使用标准转换规则转换为 `String`。根据类型，生成的字符串可能不是有效的正则表达式。如果（转换后的）参数不是有效的正则表达式，则结果为 `Undefined`。
## remainder(Decimal, Decimal)
返回第一个参数除以第二个参数的余数。等效于 [mod(Decimal, Decimal)](#iot-func-mod)。您还可以使用“%”作为相同取模功能的插入运算符。SQL 版本 2015-10-08 及更高版本支持。
示例：`remainder(8, 3)` = 2。
****
| 左侧操作数 | 右侧操作数 | Output |
| --- | --- | --- |
| Int | Int | Int，第一个参数对第二个参数取模。 |
| Int/Decimal | Int/Decimal | Decimal，第一个参数对第二个操作数取模。 |
| String/Int/Decimal | String/Int/Decimal | 如果所有字符串转换为小数，则结果为第一个参数对第二个参数取模的值。否则为 Undefined。 |
| 其它值 | 其它值 | Undefined. |
## replace(String, String, String)
用第三个参数替换在第一个参数中出现的所有第二个参数。SQL 版本 2015-10-08 及更高版本支持。
示例：
`replace("abcd", "bc", "x")` = `"axd"`.
`replace("abcdabcd", "b", "x")` = `"axcdaxcd"`.
**所有参数**
| 参数类型 | 结果 |
| --- | --- |
| Int | String 的 Int 表示形式。 |
| Decimal | String 的 Decimal 表示形式。 |
| Boolean | 布尔值（“true”或“false”）的 String 表示形式。 |
| String | 源值。 |
| 数组 | Array (使用标准转换规则) 的 String 表示形式。 |
| 对象 | 对象 (使用标准转换规则) 的 String 表示形式。 |
| Null | Undefined. |
| 未定义 | Undefined. |
## rpad(String, Int)
返回字符串参数，在输入参数的右侧填充在第二个参数中指定的数量的空格。`Int` 参数必须介于 0 到 1000 之间。如果提供的值在这一有效范围之外，则参数被设置为与其最近的值（0 或 1000）。SQL 版本 2015-10-08 及更高版本支持。
示例：
`rpad("hello", 2)` = "`hello `".
`rpad(1, 3)` = "`1 `".
****
| 参数类型 1 | 参数类型 2 | 结果 |
| --- | --- | --- |
| String | Int | 在 String 的右侧填充由 Int 指定数量的空格。 |
| String | Decimal | Decimal 参数向下舍入到最近的 Int，并且在字符串的右侧填充由 Int 指定数量的空格。 |
| String | String | 第二个参数转换为 Decimal，并向下舍入到最近的 Int。在 String 的右侧填充由 Int 值指定数量的空格。 |
| 其它值 | Int/Decimal/String | 第一个值将使用标准转换规则转换为 String，然后对该 String 应用 rpad 函数。如果它无法转换，则结果为 Undefined。 |
| 任意值 | 其它值 | Undefined. |
## round(Decimal)
将给定的 `Decimal` 舍入到最近的 `Int`。如果 `Decimal` 与上下两个 `Int` 值距离相同（例如 0.5），`Decimal` 将向上进位。SQL 版本 2015-10-08 及更高版本支持。
示例：`Round(1.2)` = 1。
`Round(1.5)` = 2。
`Round(1.7)` = 2。
`Round(-1.1)` = -1。
`Round(-1.5)` = -2。
****
| 参数类型 | 结果 |
| --- | --- |
| Int | 参数。 |
| Decimal | Decimal 会向下舍入至最近的 Int。 |
| String | Decimal 会向下舍入至最近的 Int。如果字符串无法转换为 Decimal，则结果为 Undefined。 |
| 其它值 | Undefined. |
## rtrim(String)
从提供的 `String` 中删除所有尾随空白（制表符和空格）。SQL 版本 2015-10-08 及更高版本支持。
示例：
`rtrim(" h i ")` = “h i”
****
| 参数类型 | 结果 |
| --- | --- |
| Int | String 的 Int 表示形式。 |
| Decimal | String 的 Decimal 表示形式。 |
| Boolean | 布尔值（“true”或“false”）的 String 表示形式。 |
| 数组 | Array (使用标准转换规则) 的 String 表示形式。 |
| 对象 | 对象 (使用标准转换规则) 的 String 表示形式。 |
| Null | Undefined. |
| 未定义 | Undefined |
## sign(Decimal)
返回给定数字的符号。当参数的符号为正时，将返回 1。当参数的符号为负时，将返回 -1。如果参数为 0，则返回 0。SQL 版本 2015-10-08 及更高版本支持。
示例：
`sign(-7)` = -1。
`sign(0)` = 0。
`sign(13)` = 1。
****
| 参数类型 | 结果 |
| --- | --- |
| Int | Int，Int 值的符号。 |
| Decimal | Int，Decimal 值的符号。 |
| String | Int，Decimal 值的符号。字符串将转换为 Decimal 值，并返回 Decimal 值的符号。如果 String 无法转换为 Decimal，则结果为 Undefined。SQL 版本 2015-10-08 及更高版本支持。 |
| 其它值 | Undefined. |
## sin(Decimal)
以弧度为单位返回数字的正弦值。在代入函数之前，`Decimal` 参数舍入到双精度。SQL 版本 2015-10-08 及更高版本支持。
示例：`sin(0)` = 0.0
****
| 参数类型 | 结果 |
| --- | --- |
| Int | Decimal (双精度)，参数的正弦值。 |
| Decimal | Decimal (双精度)，参数的正弦值。 |
| Boolean | Undefined. |
| String | Decimal (双精度)，参数的正弦值。如果字符串无法转换为 Decimal，则结果为 Undefined。 |
| 数组 | Undefined. |
| 对象 | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
## sinh(Decimal)
以弧度为单位返回数字的双曲正弦值。在代入函数之前，`Decimal` 值舍入到双精度。结果是双精度的 `Decimal` 值。SQL 版本 2015-10-08 及更高版本支持。
示例：`sinh(2.3)` = 4.936961805545957
****
| 参数类型 | 结果 |
| --- | --- |
| Int | Decimal (双精度)，参数的双曲正弦值。 |
| Decimal | Decimal (双精度)，参数的双曲正弦值。 |
| Boolean | Undefined. |
| String | Decimal (双精度)，参数的双曲正弦值。如果字符串无法转换为 Decimal，则结果为 Undefined。 |
| 数组 | Undefined. |
| 对象 | Undefined. |
| Null | Undefined. |
| 未定义 | Undefined. |
## sourceip()
检索设备或与之相连的路由器的 IP 地址。如果设备直接连接到互联网，该函数将返回设备的源 IP 地址。如果设备连接到与互联网相连的路由器，该函数将返回路由器的源 IP 地址。由 SQL 版本 2016-03-23 支持。`sourceip()` 不接受任何参数。
**重要**
设备的公共源 IP 地址通常是最后一个网络地址转换（NAT）网关（例如互联网服务提供商的路由器或有线调制解调器）的 IP 地址。
示例：
`sourceip()="192.158.1.38"`
`sourceip()="1.102.103.104"`
`sourceip()="2001:db8:ff00::12ab:34cd"`
SQL 示例：
`SELECT *, sourceip() as deviceIp FROM 'some/topic'`
如何在 Amazon IoT Core 规则操作中使用 sourceip () 函数的示例：
**示例 1**
以下示例说明如何在 [DynamoDB 操作](https://docs.amazonaws.cn//iot/latest/developerguide/dynamodb-rule-action.html)中调用 () 函数作为[替换模板](https://docs.amazonaws.cn//iot/latest/developerguide/iot-substitution-templates.html)。
```
{
"topicRulePayload": {
"sql": "SELECT * AS message FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"dynamoDB": {
"tableName": "my_ddb_table",
"hashKeyField": "key",
"hashKeyValue": "${sourceip()}",
"rangeKeyField": "timestamp",
"rangeKeyValue": "${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDB"
}
}
]
}
}
```
**示例 2**
以下示例说明如何使用[替换模板](https://docs.amazonaws.cn//iot/latest/developerguide/iot-substitution-templates.html)将 sourceip() 函数添加为 MQTT 用户属性。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "${topic()}/republish",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish",
"headers": {
"payloadFormatIndicator": "UTF8_DATA",
"contentType": "rule/contentType",
"correlationData": "cnVsZSBjb3JyZWxhdGlvbiBkYXRh",
"userProperties": [
{
"key": "ruleKey1",
"value": "ruleValue1"
},
{
"key": "sourceip",
"value": "${sourceip()}"
}
]
}
}
}
]
}
}
```
您可以从消息代理和[基本](https://docs.amazonaws.cn//iot/latest/developerguide/iot-basic-ingest.html)收录路径中传递给 Amazon IoT Core 规则的消息中检索源 IP 地址。您也可以检索 IPv6 消息 IPv4 和消息的源 IP。源 IP 将如下所示：
IPv6: `yyyy:yyyy:yyyy::yyyy:yyyy`
IPv4: `xxx.xxx.xxx.xxx`
**注意**
不会通过[重新发布操作](republish-rule-action.md)传递原始源 IP。
## substring(String, Int[, Int])
输入值为 `String` 后跟一个或两个 `Int` 值。对于 `String` 和单个 `Int` 参数，此函数在输入的 `String` 中从指定的 `Int` 索引（从零开始，包括零）到 `String` 结束提取子字符串并返回。对于 `String` 和两个 `Int` 参数，此函数在输入的 `String` 中从第一个 `Int` 索引参数（从零开始，包括零）到第二个 `Int` 索引参数（从零开始，包括零）提取子字符串并返回。索引小于零时将设置为零。大于 `String` 长度的索引设置为 `String` 长度。在三个参数的版本中，如果第一个索引大于等于第二个索引，那么结果为空 `String`。
如果提供的参数不是 (*String*、*Int*) 或 (*String*、*Int*、*Int*)，则将对参数应用标准转换以尝试将其转换为正确的类型。如果无法转换类型，函数的结果为 `Undefined`。SQL 版本 2015-10-08 及更高版本支持。
示例：
`substring("012345", 0)` = "012345"。
`substring("012345", 2)` = "2345"。
`substring("012345", 2.745)` = "2345"。
`substring(123, 2)` = “3”。
`substring("012345", -1)` = "012345"。
`substring(true, 1.2)` = “true”。
`substring(false, -2.411E247)` = “false”。
`substring("012345", 1, 3)` = “12”。
`substring("012345", -50, 50)` = "012345"。
`substring("012345", 3, 1)` = "".
## sql\$1version()
返回此规则中指定的 SQL 版本。SQL 版本 2015-10-08 及更高版本支持。
示例：
`sql_version()` = “2016-03-23”
## sqrt(Decimal)
返回数字的平方根。在代入函数之前，`Decimal` 参数舍入到双精度。SQL 版本 2015-10-08 及更高版本支持。
示例：`sqrt(9)` = 3.0。
****
| 参数类型 | 结果 |
| --- | --- |
| Int | 参数的平方根。 |
| Decimal | 参数的平方根。 |
| Boolean | Undefined. |
| String | 参数的平方根。如果字符串无法转换为 Decimal，则结果为 Undefined。 |
| 数组 | Undefined. |
| 对象 | Undefined. |
| Null | Undefined. |
| 未定义 | Undefined. |
## startswith(String, String)
返回显示第一个字符串参数是否以第二个字符串参数开头的 `Boolean`。如果任一参数为 `Null` 或 `Undefined`，则结果为 `Undefined`。SQL 版本 2015-10-08 及更高版本支持。
示例：
`startswith("ranger","ran")` = true
****
| 参数类型 1 | 参数类型 2 | 结果 |
| --- | --- | --- |
| String | String | 第一个字符串是否以第二个字符串开头。 |
| 其它值 | 其它值 | 两个参数都使用标准转换规则转换为字符串。如果第一个字符串以第二个字符串开头，则返回 true。如果任一参数为 Null 或 Undefined，则结果为 Undefined。 |
## tan(Decimal)
以弧度为单位返回数字的正切值。在代入函数之前，`Decimal` 值舍入到双精度。SQL 版本 2015-10-08 及更高版本支持。
示例：`tan(3)` = -0.1425465430742778
****
| 参数类型 | 结果 |
| --- | --- |
| Int | Decimal (双精度)，参数的正切值。 |
| Decimal | Decimal (双精度)，参数的正切值。 |
| Boolean | Undefined. |
| String | Decimal (双精度)，参数的正切值。如果字符串无法转换为 Decimal，则结果为 Undefined。 |
| 数组 | Undefined. |
| 对象 | Undefined. |
| Null | Undefined. |
| 未定义 | Undefined. |
## tanh(Decimal)
以弧度为单位返回数字的双曲正切值。在代入函数之前，`Decimal` 值舍入到双精度。SQL 版本 2015-10-08 及更高版本支持。
示例：`tanh(2.3)` = 0.9800963962661914
****
| 参数类型 | 结果 |
| --- | --- |
| Int | Decimal (双精度)，参数的双曲正切值。 |
| Decimal | Decimal (双精度)，参数的双曲正切值。 |
| Boolean | Undefined. |
| String | Decimal (双精度)，参数的双曲正切值。如果字符串无法转换为 Decimal，则结果为 Undefined。 |
| 数组 | Undefined. |
| 对象 | Undefined. |
| Null | Undefined. |
| 未定义 | Undefined. |
## time\$1to\$1epoch(String, String)
使用 `time_to_epoch` 函数将时间戳字符串转换为 Unix 纪元时间的毫秒数。SQL 版本 2016-03-23 及更高版本支持。要将毫秒转换为格式化的时间戳字符串，请参阅 [parse\$1time(String, Long[, String])](#iot-sql-function-parse-time)。
`time_to_epoch` 函数采用下列参数：
timestamp
（字符串）要转换为自 Unix 纪元以来毫秒数的时间戳字符串。如果时间戳字符串未指定时区，则函数将使用 UTC 时区。
模式
（字符串）遵循[JDK11 时间格式](http://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html)的 date/time 模式。
示例：
`time_to_epoch("2020-04-03 09:45:18 UTC+01:00", "yyyy-MM-dd HH:mm:ss VV")` = 1585903518000
`time_to_epoch("18 December 2015", "dd MMMM yyyy")` = 1450396800000
`time_to_epoch("2007-12-03 10:15:30.592 America/Los_Angeles", "yyyy-MM-dd HH:mm:ss.SSS z")` = 1196705730592
## timestamp()
返回规则引擎观察到的从 1970 年 1 月 1 日星期四协调世界时 (UTC) 00:00:00 开始的当前时间戳（以毫秒为单位）。 Amazon IoT SQL 版本 2015-10-08 及更高版本支持。
示例：`timestamp()` = `1481825251155`
## topic(Decimal)
返回已向其发送触发规则的消息的主题。如果未指定参数，则返回整个主题。`Decimal` 参数用于指定特定主题段，使用 1 指定第一个段。对于主题 `foo/bar/baz`，主题（1）将返回 `foo`，主题（2）将返回 `bar`，以此类推。SQL 版本 2015-10-08 及更高版本支持。
示例：
`topic()` = "things/myThings/thingOne"
`topic(1)` = “things”
在使用[基本提取](iot-basic-ingest.md)功能时，主题的初始前缀 (`$aws/rules/rule-name`) 对 topic() 函数不可用。例如，给定以下主题：
`$aws/rules/BuildingManager/Buildings/Building5/Floor2/Room201/Lights`
`topic()` = "Buildings/Building5/Floor2/Room201/Lights"
`topic(3)` = “Floor2”
## traceid()
返回 MQTT 消息的跟踪 ID（UUID），如果未通过 MQTT 发送消息，则返回 `Undefined`。SQL 版本 2015-10-08 及更高版本支持。
示例：
`traceid() ` = “12345678-1234-1234-1234-123456789012”
## transform(String, Object, Array)
返回对象数组，其中包含 `Object` 参数对 `Array` 参数的指定转换结果。
SQL 版本 2016-03-23 及更高版本支持。
字符串
要使用的转换模式。有关支持的转换模式以及这些模式如何利用 `Object` 和 `Array` 参数创建 `Result` 的信息，请参阅下表。
对象
一个对象，其中包含要应用于 `Array` 的各个元素的属性。
数组
对象的数组，其中将应用 `Object` 的属性。
此数组中的每个对象都对应于函数响应中的一个对象。函数响应中的每个对象都包含原始对象中存在的属性以及 `Object` 提供的属性，这些属性由 `String` 中指定的转换模式决定。
| `String` 参数 | `Object` 参数 | `Array` 参数 | 结果 |
| --- | --- | --- | --- |
| `enrichArray` | 对象 | 对象数组 | 一个对象的数组，其中每个对象都包含`Array` 参数中元素的属性和 `Object` 参数的属性。 |
| 其它任何值 | 任意值 | 任意值 | 未定义 |
**注意**
此函数返回的数组限制为 128 KiB。
### 变换函数示例 1
此示例演示如何使用 **transform()** 函数从数据对象和数组中生成单个对象数组。
在此示例中，将以下消息将发布到 MQTT 主题 `A/B`。
```
{
"attributes": {
"data1": 1,
"data2": 2
},
"values": [
{
"a": 3
},
{
"b": 4
},
{
"c": 5
}
]
}
```
此用于主题规则操作的 SQL 语句使用 `String` 值为 `enrichArray` 的 **transform()** 函数。在本例中，`Object` 是来自消息有效载荷的 `attributes` 属性，而 `Array` 是 `values` 数组，其中包含三个对象。
```
select value transform("enrichArray", attributes, values) from 'A/B'
```
在收到消息有效载荷后，SQL 语句将计算以下响应。
```
[
{
"a": 3,
"data1": 1,
"data2": 2
},
{
"b": 4,
"data1": 1,
"data2": 2
},
{
"c": 5,
"data1": 1,
"data2": 2
}
]
```
### 变换函数示例 2
此示例演示 **transform()** 函数如何使用文本值来包含和重命名消息有效载荷中的单个属性。
在此示例中，将以下消息将发布到 MQTT 主题 `A/B`。此消息与 [变换函数示例 1](#iot-func-transform-example1) 中使用的消息相同。
```
{
"attributes": {
"data1": 1,
"data2": 2
},
"values": [
{
"a": 3
},
{
"b": 4
},
{
"c": 5
}
]
}
```
此用于主题规则操作的 SQL 语句使用 `String` 值为 `enrichArray` 的 **transform()** 函数。**transform()** 函数中的 `Object` 在消息有效载荷中具有一个名为 `key` 的单一属性，该属性的值为 `attributes.data1`，而 `Array` 是 `values` 数组，其中包含与上一个示例中使用的三个相同对象。
```
select value transform("enrichArray", {"key": attributes.data1}, values) from 'A/B'
```
收到消息有效载荷后，此 SQL 语句将计算为以下响应。请注意 `data1` 属性在 `key` 响应中是如何命名的。
```
[
{
"a": 3,
"key": 1
},
{
"b": 4,
"key": 1
},
{
"c": 5,
"key": 1
}
]
```
### 变换函数示例 3
此示例演示如何使用 **transform()** 函数可在嵌套 SELECT 子句中选择多个属性并创建新对象以供后续处理。
在此示例中，将以下消息将发布到 MQTT 主题 `A/B`。
```
{
"data1": "example",
"data2": {
"a": "first attribute",
"b": "second attribute",
"c": [
{
"x": {
"someInt": 5,
"someString": "hello"
},
"y": true
},
{
"x": {
"someInt": 10,
"someString": "world"
},
"y": false
}
]
}
}
```
此转换函数的 `Object` 是 SELECT 语句返回的对象，其中包含消息的 `data2` 对象的 `a` 和 `b` 元素。`Array` 参数包括两个来自原始消息中 `data2.c` 数组的对象。
```
select value transform('enrichArray', (select a, b from data2), (select value c from data2)) from 'A/B'
```
借助前面的消息，SQL 语句将计算以下响应。
```
[
{
"x": {
"someInt": 5,
"someString": "hello"
},
"y": true,
"a": "first attribute",
"b": "second attribute"
},
{
"x": {
"someInt": 10,
"someString": "world"
},
"y": false,
"a": "first attribute",
"b": "second attribute"
}
]
```
此响应中返回的数组可以用于支持 `batchMode` 的主题规则操作。
## trim(String)
从提供的 `String` 中删除所有前导空白和尾随空白。SQL 版本 2015-10-08 及更高版本支持。
示例：
`Trim(" hi ") ` = "hi"
****
| 参数类型 | 结果 |
| --- | --- |
| Int | Int 在删除所有前导和尾随空白之后的 String 表示形式。 |
| Decimal | Decimal 在删除所有前导和尾随空白之后的 String 表示形式。 |
| Boolean | Boolean（“true”或“false”）在删除所有前导和尾随空白之后的 String 表示形式。 |
| String | 删除所有前导和尾随空白之后的 String。 |
| 数组 | String（使用标准转换规则）的 Array 表示形式。 |
| 对象 | 对象（使用标准转换规则）的 String 表示形式。 |
| Null | Undefined. |
| 未定义 | Undefined. |
## trunc(Decimal, Int)
按照第二个参数指定的 `Decimal` 位数截断第一个参数。如果第二个参数小于零，则它会设置为零。如果第二个参数大于 34，则它会设置为 34。将从结果中删除结尾的零。SQL 版本 2015-10-08 及更高版本支持。
示例：
`trunc(2.3, 0)` = 2。
`trunc(2.3123, 2)` = 2.31。
`trunc(2.888, 2)` = 2.88。
`trunc(2.00, 5)` = 2。
****
| 参数类型 1 | 参数类型 2 | 结果 |
| --- | --- | --- |
| Int | Int | 源值。 |
| Int/Decimal | Int/Decimal | 第一个参数被截断到由第二个参数所指定的长度。第二个参数如果不是 Int，将向下舍入至最近的 Int。 |
| Int/Decimal/String | Int/Decimal | 第一个参数被截断到由第二个参数所指定的长度。第二个参数如果不是 Int，将向下舍入至最近的 Int。String 转换为 Decimal 值。如果字符串转换失败，则结果为 Undefined。 |
| 其它值 | | Undefined. |
## upper(String)
返回给定 `String` 的大写版本。非 `String` 参数将使用标准转换规则转换为 `String`。SQL 版本 2015-10-08 及更高版本支持。
示例：
`upper("hello")` = “HELLO”
`upper(["hello"])` = “[\$1“HELLO\$1”]”
# 文本
您可以直接在规则 SQL 的 SELECT 和 WHERE 子句中指定文本对象，该对象可用于传递信息。
**注意**
文本只能在使用 SQL 版本 2016-03-23 或更高版本时使用。
使用 JSON 对象语法（键值对、逗号分隔、键为字符串/值为 JSON 值、括在大括号 \$1\$1 中）。例如：
传入负载已发布至主题 `topic/subtopic`：`{"lat_long": [47.606,-122.332]}`
SQL 语句：`SELECT {'latitude': get(lat_long, 0),'longitude':get(lat_long, 1)} as lat_long FROM 'topic/subtopic'`
生成的传出有效载荷为：`{"lat_long":{"latitude":47.606,"longitude":-122.332}}`。
您也可以在规则 SQL 的 SELECT 和 WHERE 子句中直接指定数组，用于分组信息。使用 JSON 语法（在方括号 [] 中用逗号分隔项目来创建数组文本）。例如：
传入负载已发布至主题 `topic/subtopic`：`{"lat": 47.696, "long": -122.332}`
SQL 语句：`SELECT [lat,long] as lat_long FROM 'topic/subtopic'`
生成的传出有效载荷为：`{"lat_long": [47.606,-122.332]}`。
# Case 语句
Case 语句可以用于执行分支，就像 switch 语句一样。
语法：
```
CASE v WHEN t[1] THEN r[1]
WHEN t[2] THEN r[2] ...
WHEN t[n] THEN r[n]
ELSE r[e] END
```
评估表达式 *`v`*，并与每个 `WHEN` 子句的 *`t[i]`* 值进行相等匹配。如果找到匹配，相应的 *`r[i]`* 表达式会成为 `CASE` 语句的结果。按顺序评估 `WHEN` 子句，这样，如果有多个匹配子句，第一个匹配子句的结果将成为 `CASE` 语句的结果。如果没有匹配，`ELSE` 子句的 *`r[e]`* 就是结果。如果没有匹配项且没有 `ELSE` 子句，则结果为 `Undefined`。
`CASE` 语句至少需要一个 `WHEN` 子句。`ELSE` 子句是可选的。
例如：
传入有效载荷已发布至主题 `topic/subtopic`：
```
{
"color":"yellow"
}
```
SQL 语句：
```
SELECT CASE color
WHEN 'green' THEN 'go'
WHEN 'yellow' THEN 'caution'
WHEN 'red' THEN 'stop'
ELSE 'you are not at a stop light' END as instructions
FROM 'topic/subtopic'
```
生成的传出有效载荷为：
```
{
"instructions":"caution"
}
```
**注意**
如果 *`v`* 是 `Undefined`，则 Case 语句的结果为 `Undefined`。
# JSON 扩展
您可以使用 ANSI SQL 语法的以下扩展，以便于使用嵌套 JSON 对象。
“.” 运算符
此运算符访问嵌入式 JSON 对象中的成员和函数与 ANSI SQL 和. JavaScript 例如：
```
SELECT foo.bar AS bar.baz FROM 'topic/subtopic'
```
从以下发送至 `topic/subtopic` 主题的消息有效载荷中选择 `foo` 对象中的 `bar` 属性。
```
{
"foo": {
"bar": "RED",
"bar1": "GREEN",
"bar2": "BLUE"
}
}
```
如果 JSON 属性名称包含连字符或数字字符，则“点”符号将不起作用。相反，您必须使用 [get 函数](iot-sql-functions.md#iot-sql-function-get)来提取属性的值。
在此示例中，以下消息将发送至 `iot/rules` 主题。
```
{
"mydata": {
"item2": {
"0": {
"my-key": "myValue"
}
}
}
}
```
通常情况下，`my-key` 的值将被标识为在此查询中。
```
SELECT * from iot/rules WHERE mydata.item2.0.my-key= "myValue"
```
但是，由于属性名称 `my-key` 包含连字符，而 `item2` 包含一个数字字符，因此 [get 函数](iot-sql-functions.md#iot-sql-function-get)必须按以下查询所示的方法使用。
```
SELECT * from 'iot/rules' WHERE get(get(get(mydata,"item2"),"0"),"my-key") = "myValue"
```
`*` 运算符
该运算符与 ANSI SQL 中的 `*` 通配符的运作方式相同。该运算符仅用于 SELECT 子句，并会创建包含消息数据的全新 JSON 对象。如果消息有效载荷不是 JSON 格式，`*` 将以原始字节形式返回整个消息有效载荷。例如：
```
SELECT * FROM 'topic/subtopic'
```
**将函数应用到属性值**
下面显示了一个可能由设备发布的 JSON 有效载荷示例：
```
{
"deviceid" : "iot123",
"temp" : 54.98,
"humidity" : 32.43,
"coords" : {
"latitude" : 47.615694,
"longitude" : -122.3359976
}
}
```
下面的示例将函数应用到 JSON 有效载荷中的一个属性值：
```
SELECT temp, md5(deviceid) AS hashed_id FROM topic/#
```
此查询的结果为以下 JSON 对象：
```
{
"temp": 54.98,
"hashed_id": "e37f81fb397e595c4aeb5645b8cbbbd1"
}
```
# 替换模板
您可以使用替换模板来增加触发规则并 Amazon IoT 执行操作时返回的 JSON 数据。替换模板的语法是`${`*表达式`}`，其中*表达*式*可以是 SELECT 子句、WHERE 子句和 Amazon IoT 中支持的任何表达式[Amazon IoT 规则动作](iot-rule-actions.md)。此表达式可插入到规则的操作字段中，使您可以动态配置操作。在生效时，此特征替换操作中的一段信息。这包括函数、运算符和原始消息有效载荷中存在的信息。
**重要**
因为替换模板中的表达式与“SELECT ...”语句分开评估，所以，您无法引用使用 AS 子句创建的别名。您只能引用原始有效载荷中存在的信息、[函数](iot-sql-functions.md)和[运算符](iot-sql-operators.md)。
有关支持的表达式的更多信息，请参阅[Amazon IoT SQL 参考](iot-sql-reference.md)。
以下规则操作支持替换模板。每个操作都支持不同的可替换字段。
+ [Apache Kafka](apache-kafka-rule-action.md)
+ [CloudWatch 警报](cloudwatch-alarms-rule-action.md)
+ [CloudWatch 日志](cloudwatch-logs-rule-action.md)
+ [CloudWatch 指标](cloudwatch-metrics-rule-action.md)
+ [DynamoDB](dynamodb-rule-action.md)
+ [迪纳摩 DBv2](dynamodb-v2-rule-action.md)
+ [Elasticsearch](elasticsearch-rule-action.md)
+ [HTTP](https-rule-action.md)
+ [Kinesis Data Streams](kinesis-rule-action.md)
+ [Firehose](kinesis-firehose-rule-action.md)
+ [Lambda](lambda-rule-action.md)
+ [位置](location-rule-action.md)
+ [OpenSearch](opensearch-rule-action.md)
+ [重新发布](republish-rule-action.md)
+ [S3](s3-rule-action.md)
+ [SNS](sns-rule-action.md)
+ [SQS](sqs-rule-action.md)
+ [Step Functions](stepfunctions-rule-action.md)
+ [Timestream](timestream-rule-action.md)
替换模板显示在规则内的操作参数中：
```
{
"sql": "SELECT *, timestamp() AS timestamp FROM 'my/iot/topic'",
"ruleDisabled": false,
"actions": [{
"republish": {
"topic": "${topic()}/republish",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}]
}
```
如果该规则由发布到 `my/iot/topic` 的以下 JSON 触发：
```
{
"deviceid": "iot123",
"temp": 54.98,
"humidity": 32.43,
"coords": {
"latitude": 47.615694,
"longitude": -122.3359976
}
}
```
然后，此规则将以下 JSON 发布到`my/iot/topic/republish`，其 Amazon IoT 替换为：`${topic()}/republish`
```
{
"deviceid": "iot123",
"temp": 54.98,
"humidity": 32.43,
"coords": {
"latitude": 47.615694,
"longitude": -122.3359976
},
"timestamp": 1579637878451
}
```
# 嵌套对象查询
您可以使用嵌套 SELECT 子句来查询数组和内部 JSON 对象中的属性。SQL 版本 2016-03-23 及更高版本支持。
请考虑以下 MQTT 消息：
```
{
"e": [
{ "n": "temperature", "u": "Cel", "t": 1234, "v": 22.5 },
{ "n": "light", "u": "lm", "t": 1235, "v": 135 },
{ "n": "acidity", "u": "pH", "t": 1235, "v": 7 }
]
}
```
**Example**
您可以使用以下规则将值转换为新数组。
```
SELECT (SELECT VALUE n FROM e) as sensors FROM 'my/topic'
```
该规则生成以下输出。
```
{
"sensors": [
"temperature",
"light",
"acidity"
]
}
```
**Example**
通过使用相同的 MQTT 消息，您还可以使用以下规则查询嵌套对象中的特定值。
```
SELECT (SELECT v FROM e WHERE n = 'temperature') as temperature FROM 'my/topic'
```
该规则生成以下输出。
```
{
"temperature": [
{
"v": 22.5
}
]
}
```
**Example**
您也可以使用更复杂的规则来平展输出。
```
SELECT get((SELECT v FROM e WHERE n = 'temperature'), 0).v as temperature FROM 'topic'
```
该规则生成以下输出。
```
{
"temperature": 22.5
}
```
# 使用二进制有效载荷
二进制有效载荷
当将消息有效载荷作为原始二进制数据（而不是 JSON 对象）进行处理时，可以使用 \$1 运算符在 SELECT 子句中对其进行引用。
**Topics**
+ [
## 二进制有效载荷示例
](#binary-payloads-examples)
+ [
## 解码 protobuf 消息有效载荷
](#binary-payloads-protobuf)
## 二进制有效载荷示例
当您使用 \$1 将消息有效载荷作为原始二进制数据进行引用时，您可以向规则添加数据。如果您有空的或 JSON 有效载荷，生成的有效载荷可以使用规则添加数据。下面显示了支持 `SELECT` 子句的示例。
+ 对于二进制有效载荷，您可以将以下 `SELECT` 子句仅与 \$1 一起使用。
+
```
SELECT * FROM 'topic/subtopic'
```
+
```
SELECT * FROM 'topic/subtopic' WHERE timestamp() % 12 = 0
```
+ 您还可以添加数据并使用以下 `SELECT` 子句。
+
```
SELECT *, principal() as principal, timestamp() as time FROM 'topic/subtopic'
```
+
```
SELECT encode(*, 'base64') AS data, timestamp() AS ts FROM 'topic/subtopic'
```
+ 您还可以使用带二进制有效载荷的 `SELECT` 子句。
+ 以下是指在 WHERE 子句中的 `device_type`。
```
SELECT * FROM 'topic/subtopic' WHERE device_type = 'thermostat'
```
+ 还支持以下内容。
```
{
"sql": "SELECT * FROM 'topic/subtopic'",
"actions": [
{
"republish": {
"topic": "device/${device_id}"
}
}
]
}
```
以下规则操作不支持二进制有效载荷，因此您必须对它们进行解码。
+ 一些规则操作不支持二进制有效载荷输入（例如，[Lambda 操作](https://docs.amazonaws.cn/iot/latest/developerguide/iot-rule-actions.html#lambda-rule)），您必须解码二进制有效载荷。如果 Lambda 规则操作是 base64 编码并在 JSON 有效载荷中，则可以接收二进制数据。为此，您可以将规则更改如下：
```
SELECT encode(*, 'base64') AS data FROM 'my_topic'
```
+ SQL 语句不支持字符串作为输入。要将字符串输入转换为 JSON，您可以运行以下命令。
```
SELECT decode(encode(*, 'base64'), 'base64') AS payload FROM 'topic'
```
## 解码 protobuf 消息有效载荷
[协议缓冲区（protobuf）](https://developers.google.com/protocol-buffers) 是一种开源数据格式，用于以紧凑的二进制形式序列化结构化数据。它用于通过网络传输数据或将数据存储在文件中。Protobuf 允许您以比其他消息格式更快的速度以较小的数据包大小发送数据。 Amazon IoT Core 规则通过提供[解码（值，decodingScheme）](iot-sql-functions.md#iot-sql-decode-base64)SQL 函数来支持 protobuf，该函数允许您将由 protobuf 编码的消息负载解码为 JSON 格式并将其路由到下游服务。本节详细介绍了在 “规则” 中配置 protobuf 解码的 step-by-step过程。 Amazon IoT Core
**Topics**
+ [
### 先决条件
](#binary-payloads-protobuf-prerequisites)
+ [
### 创建描述符文件
](#binary-payloads-protobuf-descriptor-steps)
+ [
### 将描述符文件上传到 S3 存储桶
](#binary-payloads-protobuf-s3-steps)
+ [
### 在规则中配置 protobuf 解码
](#binary-payloads-protobuf-steps)
+ [
### 限制
](#binary-payloads-protobuf-limitations)
+ [
### 最佳实践
](#binary-payloads-protobuf-bestpractices)
### 先决条件
+ 对[协议缓冲区（protobuf）](https://developers.google.com/protocol-buffers) 有基本的了解
+ 定义消息类型和相关依赖项的 [`.proto` 文件](https://developers.google.com/protocol-buffers/docs/proto3)
+ 在您的系统上安装 [Protobuf 编译器（protoc）](https://github.com/protocolbuffers/protobuf/releases)
### 创建描述符文件
如果您已有描述符文件，可以跳过此步骤。描述符文件 (`.desc`) 是 `.proto` 文件的编译版本，它是一个文本文件，用于定义 protobuf 序列化中使用的数据结构和消息类型。要生成描述符文件，必须定义一个 `.proto` 文件，并使用 [protoc](https://github.com/protocolbuffers/protobuf/releases) 编译器对其进行编译。
1. 创建定义消息类型的 `.proto` 文件。示例 `.proto` 文件可能如下所示：
```
syntax = "proto3";
message Person {
optional string name = 1;
optional int32 id = 2;
optional string email = 3;
}
```
在此示例 `.proto` 文件中，使用 proto3 语法并定义消息类型 `Person`。`Person` 消息定义指定三个字段（名称、ID 和电子邮件）。有关 `.proto` 文件消息格式的更多信息，请参阅[语言指南（proto3）](https://developers.google.com/protocol-buffers/docs/proto3)。
1. 使用 [protoc](https://github.com/protocolbuffers/protobuf/releases) 编译器编译 `.proto` 文件并生成一个描述符文件。创建描述符 (`.desc`) 文件的示例命令如下所示：
```
protoc --descriptor_set_out=.desc \
--proto_path= \
--include_imports \
.proto
```
此示例命令生成一个描述符文件`.desc`， Amazon IoT Core 规则可以使用该文件来解码符合中定义的数据结构的 protobuf 有效负载。`.proto`
+ `--descriptor_set_out`
指定应生成的描述符文件 (`.desc`) 的名称。
+ `--proto_path`
指定正在编译的文件所引用的任何导入的 `.proto` 文件的位置。如果您有多个位于不同位置的已导入 `.proto` 文件，可以多次指定此标志。
+ `--include_imports`
指定还应编译任何已导入的 `.proto` 文件，并将其包含在 `.desc` 描述符文件中。
+ `.proto`
指定要编译的 `.proto` 文件的名称。
有关 protoc 参考的更多信息，请参阅 [API 参考](https://developers.google.com/protocol-buffers/docs/reference/overview)。
### 将描述符文件上传到 S3 存储桶
创建描述符文件后，使用 Amazon API `.desc`、S Amazon DK 或，`.desc`将描述符文件上传到 Amazon S3 存储桶。 Amazon Web Services 管理控制台
**重要注意事项**
+ 请务必将描述符文件上传到您的 Amazon S3 存储桶，与您打算配置规则的 Amazon Web Services 区域 位置相同。 Amazon Web Services 账户
+ 请确保您授予`FileDescriptorSet`从 S3 读取的 Amazon IoT Core 权限。如果您的 S3 存储桶已禁用服务器端加密（SSE），或者 S3 存储桶已使用 Amazon S3 托管密钥（SSE-S3）加密，则不需要进行额外的策略配置。这可以通过示例存储桶策略来实现：
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "s3:Get*",
"Resource": "arn:aws:s3:::/.desc"
}
]
}
```
+ 如果您的 S3 存储桶使用 Amazon Key Management Service 密钥 (SSE-KMS) 进行加密，请确保授予在访问 S3 存储桶时使用该密钥的 Amazon IoT Core 权限。这可以通过将此语句添加到密钥策略中来实现。
```
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
```
### 在规则中配置 protobuf 解码
将描述符文件上传到 Amazon S3 桶后，配置一条[规则](https://docs.amazonaws.cn//iot/latest/developerguide/iot-create-rule.html)，该规则可以使用 [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) SQL 函数解码您的 protobuf 消息有效载荷格式。详细的函数签名和示例可以在《Amazon IoT SQL 参考》**的 [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) SQL 函数中找到。
下面是使用 [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) 函数的 SQL 表达式示例：
```
SELECT VALUE decode(*, 'proto', '', '.desc', '', '') FROM ''
```
在此示例表达式中：
+ 您可以使用 [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) SQL 函数来解码 `*` 引用的二进制消息有效载荷。这可以是 protobuf 编码的二进制有效载荷，也可以是表示 base64 编码的 protobuf 有效载荷的 JSON 字符串。
+ 提供的消息有效载荷使用中 `PROTO_FILENAME.proto` 定义的 `Person` 消息类型进行编码。
+ 名为 `BUCKET NAME` 的 Amazon S3 桶中包含从 `PROTO_FILENAME.proto` 生成的 `FILENAME.desc`。
完成配置后，向发布一条 Amazon IoT Core 有关订阅该规则的主题的消息。
### 限制
Amazon IoT Core 规则支持 protobuf，但有以下限制：
+ 不支持在[替换模板](https://docs.amazonaws.cn//iot/latest/developerguide/iot-substitution-templates.html)中解码 protobuf 消息有效载荷。
+ 解码 protobuf 消息有效载荷时，可以在单个 SQL 表达式中使用[解码 SQL 函数](iot-sql-functions.md#iot-sql-decode-base64)多达 2 次。
+ 最大入站有效载荷大小为 128 KiB（1KiB = 1024 字节），最大出站有效载荷大小为 128 KiB，存储在 Amazon S3 存储桶中的 `FileDescriptorSet` 对象的最大大小为 32 KiB。
+ 不支持使用 SSE-C 加密进行加密的 Amazon S3 存储桶。
### 最佳实践
以下是一些最佳实践和故障排除提示。
+ 在 Amazon S3 存储桶中备份您的原型文件。
备份您的原型文件是一种很好的做法，以防出现问题。例如，如果您在运行 protoc 时错误地修改了没有备份的原型文件，这可能会导致您的生产堆栈出现问题。有多种方法可以在 Amazon S3 存储桶中备份您的文件。例如，您可以[在 S3 存储桶中使用版本控制](https://docs.amazonaws.cn//AmazonS3/latest/userguide/Versioning.html)。有关如何备份 Amazon S3 存储桶中的文件的更多信息，请参阅 *[Amazon S3 开发人员指南](https://docs.amazonaws.cn//aws-backup/latest/devguide/recovery-points.html)*。
+ 配置 Amazon IoT 日志以查看日志条目。
最好配置 Amazon IoT 日志记录，这样你就可以在中查看账户的 Amazon IoT 日志 CloudWatch。当规则的 SQL 查询调用外部函数时， Amazon IoT Core Rules 会生成一个带为`eventType`的日志条目`FunctionExecution`，其中包含可帮助您排除故障原因字段。可能的错误包括找不到 Amazon S3 对象，或者 protobuf 文件描述符无效。有关如何配置 Amazon IoT 日志记录和查看日志条目的更多信息，请参阅[配置 Amazon IoT 日志记录](https://docs.amazonaws.cn//iot/latest/developerguide/configure-logging.html)和[规则引擎日志条目](https://docs.amazonaws.cn//iot/latest/developerguide/cwl-format.html#log-rules-fn-exec)。
+ 使用新的对象键更新 `FileDescriptorSet`，并更新规则中的对象键。
您可以通过将更新后的描述符文件上传到 Amazon S3 桶来更新 `FileDescriptorSet`。您对 `FileDescriptorSet` 的更新最多需要 15 分钟能够反映出来。为了避免这一延迟，使用新的对象键上传更新后的 `FileDescriptorSet`，然后更新规则中的此对象密钥是一种很好的做法。
# SQL 版本
Amazon IoT 规则引擎使用类似 SQL 的语法从 MQTT 消息中选择数据。SQL 语句基于 SQL 版本进行解释，该版本由描述此规则的 JSON 文档中的 `awsIotSqlVersion` 属性指定。有关 JSON 规则文档结构的更多信息，请参阅[创建规则](iot-create-rule.md)。该`awsIotSqlVersion`属性允许您指定要使用的 Amazon IoT SQL 规则引擎版本。当部署新版本时，您可以继续使用早期版本或更改规则以使用新版本。您当前的规则将继续使用创建时所用的版本。
以下 JSON 示例介绍了如何使用 `awsIotSqlVersion` 属性指定 SQL 版本：
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [{
"republish": {
"topic": "my-mqtt-topic",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}]
}
```
Amazon IoT 目前支持以下 SQL 版本：
+ `2016-03-23` – 2016 年 3 月 23 日构建的 SQL 版本（建议）。
+ `2015-10-08` – 2015 年 10 月 8 日构建的 SQL 原始版本。
+ `beta` – 最新的 SQL 测试版本。此版本可能会给您的规则带来突破性变化。
## 2016-03-23 SQL 规则引擎版本中的新增功能
+ 针对选择嵌套 JSON 对象的修复程序。
+ 针对阵列查询的修复程序。
+ 对象内查询支持。有关更多信息，请参阅 [嵌套对象查询](iot-sql-nested-queries.md)。
+ 支持将阵列作为顶级对象输出。
+ 添加可应用于 JSON 和非 JSON 格式数据的 `encode(value, encodingScheme)` 函数。有关更多信息，请参阅[编码函数](iot-sql-functions.md#iot-sql-encode-payload)。
### 将 `Array` 作为顶级对象输出
此特征允许规则将阵列作为顶级对象返回。例如，给定了以下 MQTT 消息：
```
{
"a": {"b":"c"},
"arr":[1,2,3,4]
}
```
以及以下规则：
```
SELECT VALUE arr FROM 'topic'
```
该规则生成以下输出。
```
[1,2,3,4]
```