本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 的規則 AWS IoT
規則可讓您的裝置與 互動 AWS 服務。規則的分析和動作的執行均是以 MQTT 的主題流為依歸。您可以使用規則來支援下列任務：
+ 擴增或篩選從裝置接收的資料
+ 將裝置接收的資料寫入 Amazon DynamoDB 資料庫。
+ 將檔案儲存至 Amazon S3。
+ 使用 Amazon SNS 將推送通知傳送給所有使用者。
+ 將資料發佈至 Amazon SQS 佇列。
+ 呼叫 Lambda 函數來擷取資料。
+ 使用 Amazon Kinesis 來處理來自大量裝置的訊息。
+ 將資料傳送至 Amazon OpenSearch Service。
+ 擷取 CloudWatch 指標。
+ 變更 CloudWatch 警示。
+ 將資料從 MQTT 訊息傳送至 Amazon SageMaker AI，以根據機器學習 (ML) 模型進行預測。
+ 將訊息傳送至 Salesforce IoT 輸入串流。
+ 開始處理 Step Functions 狀態機器。
+ 將訊息資料傳送至 AWS IoT Events 輸入。
+ 將訊息資料傳送至 AWS IoT SiteWise中的資產屬性。
+ 將訊息資料傳送至 Web 應用程式或服務。
您的規則可以使用 MQTT 訊息，這些訊息會通過 [裝置通訊協定](protocols.md) 支援的發佈/訂閱協定。您也可以使用[基本擷取](iot-basic-ingest.md)功能，安全地將裝置資料傳送至先前 AWS 服務 列出的 ，而不會產生[簡訊費用](https://aws.amazon.com/iot-core/pricing/)。[基本擷取](iot-basic-ingest.md)功能會從擷取路徑移除發佈/訂閱訊息代理程式，使資料流程最佳化。這使得它具有成本效益，同時仍保有 的安全性和資料處理功能 AWS IoT。
在 AWS IoT 可以執行這些動作之前，您必須授予它代表您存取 資源 AWS 的許可。執行動作時，您需為您使用的 AWS 服務 支付標準費用。
**Topics**
+ [授予 AWS IoT 規則所需的存取權](iot-create-role.md)
+ [傳遞角色許可](pass-role.md)
+ [建立 AWS IoT 規則](iot-create-rule.md)
+ [管理 AWS IoT 規則](iot-managae-rule.md)
+ [AWS IoT 規則動作](iot-rule-actions.md)
+ [規則疑難排解](#iot-troubleshoot-rule)
+ [使用 AWS IoT 規則存取跨帳戶資源](accessing-cross-account-resources-using-rules.md)
+ [錯誤處理 (錯誤動作)](rule-error-handling.md)
+ [使用基本擷取減少簡訊費用](iot-basic-ingest.md)
+ [AWS IoT SQL 參考](iot-sql-reference.md)
# 授予 AWS IoT 規則所需的存取權
使用 IAM 角色來控制每個規則可存取 AWS 的資源。建立規則之前，您必須使用允許存取所需 AWS 資源的政策來建立 IAM 角色。在實作規則時 AWS IoT ， 會擔任此角色。
**完成下列步驟以建立 IAM 角色和 AWS IoT 政策，授予 AWS IoT 規則所需的存取權 (AWS CLI)。**
1. 將下列信任政策文件儲存至名為 的檔案，以授予擔任該角色的 AWS 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.aws.amazon.com/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 是授予 AWS IoT 管理員 DynamoDB 存取權的範例政策文件。
使用 [create-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) 命令，在擔任角色時授予 AWS 資源的 AWS IoT 存取權，並傳入 `my-iot-policy.json` 檔案：
```
aws iam create-policy --policy-name my-iot-policy --policy-document file://my-iot-policy.json
```
如需如何在 政策 AWS 服務 中授予 存取權的詳細資訊 AWS IoT，請參閱 [建立 AWS IoT 規則](iot-create-rule.md)。
[create-policy](https://docs.aws.amazon.com/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.aws.amazon.com/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.aws.amazon.com/iot/latest/developerguide/iot-create-role.html)中移除 iot.amazonaws.com
1. 依照步驟[撤銷 iot 角色工作階段](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_revoke-sessions.html)
# 傳遞角色許可
IAM 角色是規則定義的一部分，其授予指定於規則動作中資源的存取許可。當叫用規則的動作時，規則引擎會擔任該角色。角色必須在 AWS 帳戶 與規則相同的 中定義。
當建立或替換某項規則時，實際上就是在將某個角色傳送至規則引擎。執行此操作需要 `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.aws.amazon.com/service-authorization/latest/reference/access_policies_managed-using.html)。
**注意**
Lambda 函數使用的是資源型政策，即是政策直接連接至 Lambda 函數本身。在您建立一個叫用 Lambda 函數的規則時，並不會傳遞角色，因此建立該規則的使用者不需要 `iam:PassRole` 許可。如需 Lambda 函數授權的詳細資訊，請參閱[使用資源政策授予許可](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html#intro-permission-model-access-policy)。
# 建立 AWS IoT 規則
您可以建立 AWS IoT 規則，從連線的實物路由資料，以與其他 AWS 服務互動。 AWS IoT 規則包含下列元件：
**規則的元件**
| 元件 | Description | 必要或選用 |
| --- | --- | --- |
| 規則名稱 | 規則的名稱。請注意，我們不建議您在規則名稱中使用個人身分識別資訊。 | 必要. |
| 規則說明 | 規則的文字描述。請注意，我們不建議您在規則描述中使用個人身分識別資訊。 | 選用。 |
| SQL 陳述式 | 簡化的 SQL 語法，用於篩選 MQTT 主題所收到的訊息，並將資料推送到他處。如需詳細資訊，請參閱[AWS IoT SQL 參考](iot-sql-reference.md)。 | 必要. |
| SQL 版本 | 評估規則時所用的 SQL 規則引擎版本。雖然此屬性是選用的，但強烈建議您指定 SQL 版本。根據`2016-03-23`預設， AWS IoT Core 主控台會將此屬性設定為 。如果未設定此屬性，例如在 AWS CLI 命令或 CloudFormation 範本中，`2015-10-08`則會使用 。如需詳細資訊，請參閱[SQL 版本](iot-rule-sql-version.md)。 | 必要. |
| 一或多個動作 | 動作會在制定規則時 AWS IoT 執行。例如，您可將資料插入 DynamoDB 表格，將資料寫入 Amazon S3 儲存貯體，發佈至 Amazon SNS 主題，或呼叫 Lambda 函式。 | 必要. |
| 錯誤動作 | 動作 AWS IoT 會在無法執行規則的動作時執行。 | 選用。 |
建立 AWS IoT 規則之前，您必須使用允許存取所需 AWS 資源的政策來建立 IAM 角色。在實作規則時 AWS IoT ， 會擔任此角色。如需詳細資訊，請參閱[授予 AWS IoT 規則所需的存取權](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-role.html)和[傳遞角色許可](https://docs.aws.amazon.com//iot/latest/developerguide/pass-role.html)。
建立規則時，請注意在主題上發佈的資料量。如果您建立了包含萬用字元主題模式的規則，這些規則可能會比對大部分的訊息。若是這種情況，您可能需要增加目標動作使用的 AWS 資源容量。我們建議在重新發佈規則中避免萬用字元主題模式，以防止重複處理並降低成本。
**注意**
規則的建立和更新是屬於管理員層級的動作。任何擁有許可而能建立或更新規則的使用者，均能夠存取規則所處理的資料。
## 建立規則 （主控台）
**建立規則 (AWS 管理主控台)**
使用 [AWS 管理主控台](https://console.aws.amazon.com//iot/home#/home)命令來建立規則：
1. 開啟 [AWS IoT 主控台](https://console.aws.amazon.com//iot/home#/home)。
1. 在左側導覽上，從**管理**區段中選擇**訊息路由**。然後選擇**規則**。
1. 在**規則**頁面上，選擇**建立規則**。
1. 在**指定規則屬性**頁面上，輸入規則的名稱。**規則描述**和**標籤**是選用的。選擇**下一步**。
1. 在**設定 SQL 陳述**式頁面上，選擇 SQL 版本並輸入 SQL 陳述式。SQL 陳述式的範例可以是 `SELECT temperature FROM 'iot/topic' WHERE temperature > 50`。如需詳細資訊，請參閱 [SQL 版本](https://docs.aws.amazon.com//iot/latest/developerguide/iot-rule-sql-version.html)和 [AWS IoT SQL 參考](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-reference.html)。
1. 在**連接規則動作**頁面上，新增規則動作以將資料路由至其他服務 AWS 。
1. 在**規則動作**中，從下拉式清單中選取規則動作。例如，您可以選擇 **Kinesis Stream**。如需規則動作的詳細資訊，請參閱[AWS IoT 規則動作](https://docs.aws.amazon.com//iot/latest/developerguide/iot-rule-actions.html)。
1. 根據您選擇的規則動作，輸入相關的組態詳細資訊。例如，如果您選擇 **Kinesis Stream**，您將需要選擇或建立資料串流資源，並選擇性地輸入組態詳細資訊，例如**分割區索引鍵**，用於在蒸汽中依碎片分組資料。
1. 在 **IAM 角色**中，選擇或建立角色以授予對端點的 AWS IoT 存取權。請注意， AWS IoT 會自動在您的 IAM 角色`aws-iot-rule`下建立字首為 的政策。您可以選擇**檢視**，從 IAM 主控台檢視您的 IAM 角色和政策。**錯誤動作**是選用的。您可以在[錯誤處理 （錯誤動作）](https://docs.aws.amazon.com//iot/latest/developerguide/rule-error-handling.html) 中找到更多資訊。如需為規則建立 IAM 角色的詳細資訊，請參閱[授予規則所需的存取權](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-role.html)。選擇**下一步**。
1. 在**檢閱和建立**頁面上，檢閱所有組態並視需要進行編輯。選擇**建立**。
成功建立規則後，您會在規則頁面上看到列出的**規則**。您可以選擇規則以開啟**詳細資訊**頁面，您可以在其中檢視規則、編輯規則、停用規則，以及刪除規則。
## 建立規則 (CLI)
**建立規則 (AWS CLI)**
請使用 [create-topic-rule](https://docs.aws.amazon.com/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 資料表的 AWS 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 儲存貯體的 AWS 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 Service: 的規則：
```
{
"sql": "SELECT *, timestamp() as timestamp FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"OpenSearch": {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_es",
"endpoint": "https://my-endpoint",
"index": "my-index",
"type": "my-type",
"id": "${newuuid()}"
}
}
]
}
```
下列為範例承載檔案，具有會呼叫 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"
}
}
]
}
```
以下是範例承載檔案，其中包含使用 Amazon SageMaker AI `machinelearning_predict`函數重新發佈至主題的規則，如果 MQTT 承載中的資料分類為 1。
```
{
"sql": "SELECT * FROM 'iot/test' where machinelearning_predict('my-model', 'arn:aws:iam::123456789012:role/my-iot-aml-role', *).predictedLabel=1",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role",
"topic": "my-mqtt-topic"
}
}
]
}
```
以下是範例承載檔案，含有的規則會將訊息發佈至 Salesforce IoT 雲端輸入串流：
```
{
"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"
}
}
]
}
```
# 管理 AWS IoT 規則
您可以使用下列動作來管理您的 AWS IoT 規則。
**Topics**
+ [標記規則](#iot-create-rule-tagging)
+ [檢視規則](#iot-view-rules)
+ [刪除規則](#iot-delete-rule)
## 標記規則
您可以套用標記，將另一層特殊性新增至新規則或現有規則。標記會利用規則中的鍵/值對，讓您更能控制規則套用至 AWS IoT 資源和服務的方式和位置。例如，您可以將規則範圍限制為僅適用於進行發行前測試的試用版環境 (`Key=environment, Value=beta`)，或擷取所有僅從特定端點傳送至 `iot/test` 的主題，並將這兩項資料存放在 Amazon S3 儲存貯體中。
### IAM 政策範例
對於示範如何授予規則標記許可的範例，請考慮使用者執行以下命令，以建立規則並將其標記為僅適用於試用版環境。
在該範例中，替換：
+ *MyTopleName* 為規則的名稱。
+ *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` 並僅適用於試用版環境的新建規則。政策聲明中的 `iot:TagResource` 與 `MyTopicRuleName` 特別呼叫，允許在建立或更新 `MyTopicRuleName` 時予以標記。建立規則時使用的參數 `--tags "environment=beta"` 將 `MyTopicRuleName` 範圍限制為只有您的測試版環境。如果您移除參數 `--tags "environment=beta"`，`MyTopicRuleName` 將適用於所有環境。
如需根據 AWS IoT 規則建立 IAM 角色和政策的詳細資料，請參閱 [授予 AWS IoT 規則所需的存取權](iot-create-role.md)
如需標記資源的相關資訊，請參閱 [標記您的 AWS IoT 資源](tagging-iot.md)。
## 檢視規則
請使用 [list-topic-rules](https://docs.aws.amazon.com/cli/latest/reference/iot/list-topic-rules.html) 命令來列出規則：
```
aws iot list-topic-rules
```
請使用 [get-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/get-topic-rule.html) 命令來取得規則的相關資訊：
```
aws iot get-topic-rule --rule-name myrule
```
## 刪除規則
規則結束使用後即可刪除。
**刪除規則 (AWS CLI)**
請使用 [delete-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-topic-rule.html) 命令來刪除規則：
```
aws iot delete-topic-rule --rule-name myrule
```
# AWS IoT 規則動作
AWS IoT 規則動作指定呼叫規則時要執行的動作。您可以定義動作，將資料傳送至 Amazon DynamoDB 資料庫、將資料傳送至 Amazon Kinesis Data Streams、叫用 AWS Lambda 函數等。 AWS IoT 支援下列動作， AWS 區域 其中提供動作的服務。
| 規則動作 | Description | API 中的名稱 |
| --- | --- | --- |
| [Apache Kafka](apache-kafka-rule-action.md) | 將訊息傳送至 Apache Kafka 叢集。 | kafka |
| [CloudWatch 警示](cloudwatch-alarms-rule-action.md) | 變更 Amazon CloudWatch 警示的狀態。 | cloudwatchAlarm |
| [CloudWatch Logs](cloudwatch-logs-rule-action.md) | 將訊息傳送至 Amazon CloudWatch Logs。 | cloudwatchLogs |
| [CloudWatch 指標](cloudwatch-metrics-rule-action.md) | 將訊息傳送至 CloudWatch 指標。 | cloudwatchMetric |
| [DynamoDB](dynamodb-rule-action.md) | 將訊息傳送至 DynamoDB 表格。 | dynamoDB |
| [DynamoDBv2](dynamodb-v2-rule-action.md) | 將訊息資料傳送至 DynamoDB 表格中的多個欄。 | dynamoDBv2 |
| [Elasticsearch](elasticsearch-rule-action.md) | 將訊息傳送至 OpenSearch 端點。 | OpenSearch |
| [HTTP](https-rule-action.md) | 將訊息發佈至 HTTPS 端點。 | http |
| [AWS IoT Events](iotevents-rule-action.md) | 傳送訊息至 AWS IoT Events 輸入。 | iotEvents |
| [AWS IoT SiteWise](iotsitewise-rule-action.md) | 傳送訊息資料至 AWS 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](location-rule-action.md) | 將位置資料傳送至 Amazon Location Service。 | location |
| [OpenSearch](opensearch-rule-action.md) | 將訊息傳送至 Amazon OpenSearch Service 端點。 | OpenSearch |
| [重新發佈](republish-rule-action.md) | 可在另一個 MQTT 主題上重新發佈訊息。 | republish |
| [S3](s3-rule-action.md) | 將訊息存放於 Amazon Simple Storage Service (Amazon S3) 儲存貯體中。 | s3 |
| [Salesforce IoT](salesforce-iot-rule-action.md) | 傳送訊息至 Salesforce IoT 輸入串流。 | 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 |
| [步驟函數](stepfunctions-rule-action.md) | 啟動 AWS Step Functions 狀態機器。 | stepFunctions |
| [Timestream](timestream-rule-action.md) | 將訊息傳送至 Amazon Timestream 資料庫表格。 | timestream |
**備註**
在與其他服務資源 AWS 區域 相同的 中定義規則，以便規則動作可以與該資源互動。
如果發生間歇性錯誤， AWS IoT 規則引擎可能會多次嘗試執行動作。若所有嘗試都失敗了，則該訊息將遭捨棄，而且可在您的 CloudWatch Logs 中取得錯誤。您可以為失敗發生之後調用的每一個規則指定一個錯誤動作。如需詳細資訊，請參閱[錯誤處理 (錯誤動作)](rule-error-handling.md)。
某些規則動作會啟動服務中與 AWS Key Management Service (AWS KMS) 整合的動作，以支援靜態資料加密。如果您使用客戶受管 AWS KMS key (KMS 金鑰） 加密靜態資料，服務必須具有代表發起人使用 KMS 金鑰的許可。若要了解如何管理客戶受管 KMS 金鑰的許可，請參閱適當服務指南中的資料加密主題。如需客戶受管 KMS 金鑰的詳細資訊，請參閱《AWS Key Management Service 開發人員指南》**中的 [AWS Key Management Service 概念](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html)。
您可以在錯誤動作的 SQL 陳述式中使用任何[函數](iot-sql-functions.md)或[替代範本](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html)，包括外部函數：[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda)、[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb)、[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data)、[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow)[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret)、[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning)、 和 [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64)。如果錯誤動作需要呼叫外部 函數，則叫用錯誤動作可能會導致外部函數產生額外的帳單。
# Apache Kafka
Apache Kafka (Kafka) 動作會將訊息直接傳送到您的 [Amazon Managed Streaming for Apache Kafka](https://docs.aws.amazon.com//msk/latest/developerguide/what-is-msk.html) (Amazon MSK)、由 [Confluent Cloud](https://www.confluent.io/) 等第三方供應商管理的 Apache Kafka 叢集，或自我管理的 Apache Kafka 叢集。使用 Kafka 規則動作，您可以將 IoT 資料路由到 Kafka 叢集。這可讓您針對各種用途建置高效能資料管道，例如串流分析、資料整合、視覺化和關鍵任務業務應用程式。
**注意**
本主題假設您熟悉 Apache Kafka 平台及相關概念。如需有關 Apache Kafka 的詳細資訊，請參閱 [Apache Kafka](https://kafka.apache.org/)。不支援 [MSK Serverless](https://docs.aws.amazon.com//msk/latest/developerguide/serverless.html)。MSK Serverless 叢集只能透過 Apache Kafka 規則動作目前不支援的 IAM 身分驗證來完成。如需如何使用 AWS IoT Core Confluent 設定 的詳細資訊，請參閱[利用 Confluent 和 AWS 來解決 IoT 裝置和資料管理挑戰](https://aws.amazon.com/blogs/apn/leveraging-confluent-and-aws-to-solve-iot-device-and-data-management-challenges/)。
## 要求
此規則動作具有下列需求：
+ AWS IoT 可以擔任以執行 `ec2:CreateNetworkInterface`、`ec2:DescribeNetworkInterfaces`、、`ec2:CreateNetworkInterfacePermission``ec2:DeleteNetworkInterface`、、`ec2:DescribeVpcs`、 `ec2:DescribeVpcAttribute`和 `ec2:DescribeSecurityGroups`操作的 `ec2:DescribeSubnets`IAM 角色。此角色會建立並管理您 Amazon Virtual Private Cloud 的彈性網路介面，以達到您的 Kafka 代理程式。如需詳細資訊，請參閱[授予 AWS IoT 規則所需的存取權](iot-create-role.md)。
在 AWS IoT 主控台中，您可以選擇或建立角色， AWS IoT Core 以允許 執行此規則動作。
如需有關網路介面的詳細資訊，請參閱《Amazon EC2 使用者指南》**中的[彈性網路介面](https://docs.aws.amazon.com/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": "*"
}
]
}
```
+ 如果您使用 AWS Secrets Manager 來存放連線至 Kafka 代理程式所需的登入資料，則必須建立 AWS IoT Core 可擔任的 IAM 角色，以執行 `secretsmanager:GetSecretValue`和 `secretsmanager:DescribeSecret`操作。
連接至您指定之角色的政策應如下列範例所示：
****
```
{
"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 Virtual Private Cloud (VPC) 目的地，並使用子網路中的 NAT 閘道，將訊息從 轉送 AWS IoT 到公有 Kafka 叢集。 AWS IoT 規則引擎會在目的地中列出的每個子網路中建立網路介面，將流量直接路由到 VPC。當您到達目的地時， AWS IoT 規則引擎會自動建立 VPC 規則動作。如需有關 VPC 規則動作的詳細資訊，請參閱 [Apache Kafka Virtual Private Cloud (VPC) 目的地](kafka-vpc-destination.md)。
+ 如果您使用客戶受管 AWS KMS key (KMS 金鑰） 來加密靜態資料，服務必須具有代表發起人使用 KMS 金鑰的許可。如需詳細資訊，請參閱《Amazon Managed Streaming for Apache Kafka 開發人員指南》**中的 [Amazon MSK 加密](https://docs.aws.amazon.com/msk/latest/developerguide/msk-encryption.html)。
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
destinationArn
Apache Kafka Virtual Private Cloud (VPC) 目的地的 Amazon Resource Name (ARN)。如需建立目的地的詳細資訊，請參閱 [Apache Kafka Virtual Private Cloud (VPC) 目的地](kafka-vpc-destination.md)。
主題
要傳送至 Kafka 代理程式之訊息的 Kafka 主題。
您可使用替代範本來替代此欄位。如需詳細資訊，請參閱[替代範本](iot-substitution-templates.md)。
金鑰 (選用)
Kafka 訊息金鑰。
您可使用替代範本來替代此欄位。如需詳細資訊，請參閱[替代範本](iot-substitution-templates.md)。
標頭 (選用)
您指定的 Kafka 標頭清單。每個標頭都是鍵值對，您可以在建立 Kafka 動作時指定。您可以使用這些標頭將資料從 IoT 用戶端路由到下游 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
用來建立 Kafka 叢集初始連線的主機和連接埠配對清單 (例如 `host1:port1`、`host2:port2`)。
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 格式的信任庫檔案或在 [AWS Secrets Manager](https://docs.aws.amazon.com/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、us-gov-east-1 和 us-gov-west-1 區域中唯一支援的安全機制。
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 範例定義 AWS IoT 規則中的 Apache Kafka 動作。以下範例會在 Kafka 動作標頭中傳遞 [sourceIp()](iot-sql-functions.md#iot-function-sourceip) 內嵌函數作為[替換範本](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html)。
```
{
"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.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-private.html)。
+ 每個 VPC 皆必須啟用 DNS 解析。如需詳細資訊，請參閱[以 VPC 使用 DNS](https://docs.aws.amazon.com/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、us-gov-east-1 和 us-gov-west-1 區域中唯一支援的安全機制。
# Apache Kafka Virtual Private Cloud (VPC) 目的地
Apache Kafka 規則動作將資料路由至 Amazon Virtual Private Cloud (Amazon VPC) 中的 Apache Kafka 叢集。在為規則動作指定 VPC 目的地時，系統會自動啟用 Apache Kafka 規則動作所使用的 VPC 組態。
Apache Kafka Virtual Private Cloud (VPC) 目的地包含 VPC 內的子網路清單。規則引擎會在您於此清單中指定的每個子網路中建立彈性網路介面。如需有關網路介面的詳細資訊，請參閱《Amazon EC2 使用者指南》中的[彈性網路介面](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html)。
## 需求和考量事項
+ 如果您使用的是將由公有端點透過網際網路存取的自我管理 Apache Kafka 叢集：
+ 為子網路中的執行個體建立 NAT 閘道。NAT 閘道具有可連接到網際網路的公有 IP 地址，允許規則引擎將您的訊息轉發到公有 Kafka 叢集。
+ 使用 Apache Kafka Virtual Private Cloud (VPC) 目的地建立的彈性網路介面 (ENIs) 來配置彈性 IP 地址。您使用的安全群組必須配置為封鎖傳入流量。
**注意**
如果 Apache Kafka Virtual Private Cloud (VPC) 目的地已停用，然後重新啟用，您必須重新建立彈性 IPs與新 ENIs關聯。
+ 如果 Apache Kafka Virtual Private Cloud (VPC) 目的地連續 30 天未收到任何流量，則會停用。
+ 如果 Apache Kafka Virtual Private Cloud (VPC) 目的地使用的任何資源變更，則會停用目的地且無法使用。
+ 可以停用 Apache Kafka Virtual Private Cloud (VPC) 目的地的一些變更包括：
+ 刪除 VPC、子網路、安全群組或使用的角色。
+ 將角色修改為不再具有必要的許可。
+ 達到接近子網路容量，這使得我們無法套用 [ FedRAMP](https://aws.amazon.com/compliance/fedramp/) 修補。
+ 停用目的地。
## 定價
基於定價目的，除了資源位於您 VPC 中時將訊息傳送至資源之外，還會計量 VPC 規則動作。如需定價資訊，請參閱 [AWS IoT Core 定價](https://aws.amazon.com/iot-core/pricing/)。
## 建立 Apache Kafka Virtual Private Cloud (VPC) 目的地
您可以使用 [CreateTopicRuleDestination](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRuleDestination.html) API 或 AWS IoT Core 主控台建立 Apache Kafka Virtual Private Cloud (VPC) 目的地。
建立目的地時，您必須指定下列資訊。
vpcId
Amazon 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 Virtual Private Cloud (VPC) 目的地 AWS CLI
下列範例示範如何使用 建立目的地 AWS 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 Virtual Private Cloud (VPC) 目的地的狀態。
```
aws --region region iot get-topic-rule-destination --arn "VPCDestinationARN"
```
### 使用 AWS IoT Core 主控台建立 Apache Kafka Virtual Private Cloud (VPC) 目的地
下列步驟說明如何使用 AWS IoT Core 主控台建立目的地。
1. 導覽至 AWS IoT Core 主控台。在左窗格的**動作**索引標籤上，選擇**目的地**。
1. 請輸入下列欄位的值。
+ **VPC ID**
+ **子網路 ID**
+ **安全群組**
1. 選取具有建立網路介面所需許可的角色。上述範例政策包含這些許可。
當 Apache Kafka Virtual Private Cloud (VPC) 目的地狀態為 **ENABLED** 時，即可開始使用。
# CloudWatch 警示
CloudWatch 警示 (`cloudWatchAlarm`) 動作變更 Amazon CloudWatch 警示的狀態。您可以指定此呼叫狀態變更的原因和值。
## 要求
此規則動作具有下列需求：
+ AWS IoT 可以擔任以執行`cloudwatch:SetAlarmState`操作的 IAM 角色。如需詳細資訊，請參閱[授予 AWS IoT 規則所需的存取權](iot-create-role.md)。
在 AWS IoT 主控台中，您可以選擇或建立角色， AWS IoT 以允許 執行此規則動作。
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
`alarmName`
CloudWatch 警示名稱。
僅支援[替代範本](iot-substitution-templates.md)：API 和 AWS 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 範例定義 AWS 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"
}
}
]
}
}
```
## 另請參閱
+ 《Amazon CloudWatch 使用者指南》**中的[什麼是 Amazon CloudWatch？](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)
+ 《Amazon CloudWatch 使用者指南》**中的[使用 Amazon CloudWatch 警示](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)
# CloudWatch Logs
CloudWatch Logs (`cloudwatchLogs`) 動作會將資料傳送至 Amazon CloudWatch Logs。您可以使用 `batchMode`，以一則訊息上傳多個裝置日誌記錄並加上時間戳記。您也可以指定動作傳送資料的日誌群組。
## 要求
此規則動作具有下列需求：
+ AWS IoT 可以擔任以執行 `logs:CreateLogStream`、 `logs:DescribeLogStreams`和 `logs:PutLogEvents`操作的 IAM 角色。如需詳細資訊，請參閱[授予 AWS IoT 規則所需的存取權](iot-create-role.md)。
在 AWS IoT 主控台中，您可以選擇或建立角色， AWS IoT 以允許 執行此規則動作。
+ 如果您使用客戶受管 AWS KMS key (KMS 金鑰） 來加密 CloudWatch Logs 中的日誌資料，則服務必須具有代表發起人使用 KMS 金鑰的許可。如需詳細資訊，請參閱《Amazon CloudWatch Logs 使用者指南》**中[使用 AWS KMS加密 CloudWatch Logs 中的日誌資料](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/encrypt-log-data-kms.html)。
## `batchMode` 的 MQTT 訊息格式需求
如果您在關閉 `batchMode` 的情況下使用 CloudWatch Logs 規則動作，則不需要 MQTT 訊息格式設定。(注意：`batchMode` 參數的預設值為 `false`。) 不過，如果您在 `batchMode` 開啟的情況下使用 CloudWatch Logs 規則動作 (參數值為 `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.aws.amazon.com/iot/latest/developerguide/topicdata.html)。
與 `batchMode` 參數無關，`message`內容必須符合 AWS IoT 訊息大小限制。如需詳細資訊，請參閱 [AWS IoT Core 端點和配額](https://docs.aws.amazon.com/general/latest/gr/iot-core.html)。
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
`logGroupName`
其動作傳送資料的 CloudWatch 日誌群組。
僅支援[替代範本](iot-substitution-templates.md)：API 和 AWS CLI
`roleArn`
允許存取 CloudWatch Logs 群組的 IAM 角色。如需詳細資訊，請參閱[要求](#cloudwatch-logs-rule-action-requirements)。
支援[替代範本](iot-substitution-templates.md)：否
（選用） `batchMode`
指出是否要擷取日誌記錄批次並上傳至 CloudWatch。值包括 `true` 或 `false` (預設值)。如需詳細資訊，請參閱[要求](#cloudwatch-logs-rule-action-requirements)。
支援[替代範本](iot-substitution-templates.md)：否
## 範例
下列 JSON 範例會在 AWS IoT 規則中定義 CloudWatch Logs 動作。
```
{
"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 Logs 使用者指南》**中的[什麼是 Amazon CloudWatch Logs？](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/)
# CloudWatch 指標
CloudWatch 指標 (`cloudwatchMetric`) 動作擷取 Amazon CloudWatch 指標。您可以指定指標命名空間、名稱、值、單位、時間戳記。
## 要求
此規則動作具有下列需求：
+ AWS IoT 可以擔任以執行`cloudwatch:PutMetricData`操作的 IAM 角色。如需詳細資訊，請參閱[授予 AWS IoT 規則所需的存取權](iot-create-role.md)。
在 AWS IoT 主控台中，您可以選擇或建立角色， AWS IoT 以允許 執行此規則動作。
## Parameters
當您使用此動作建立 AWS 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 epoch 時間中時間戳記 (以秒為單位來表達) 的字串。預設為目前的 Unix epoch 時間。
支援[替代範本](iot-substitution-templates.md)：是
`roleArn`
允許存取 CloudWatch 指標的 IAM 角色。如需詳細資訊，請參閱[要求](#cloudwatch-metrics-rule-action-requirements)。
支援[替代範本](iot-substitution-templates.md)：否
## 範例
下面的 JSON 範例定義 AWS 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 範例使用 AWS 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"
}
}
]
}
}
```
## 另請參閱
+ 《Amazon CloudWatch 使用者指南》**中的[什麼是 Amazon CloudWatch？](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)
+ 《Amazon CloudWatch 使用者指南》**中的[使用 Amazon CloudWatch 指標](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html)
# DynamoDB
DynamoDB (`dynamoDB`) 動作會將 MQTT 訊息的全部或部分寫入 Amazon DynamoDB 表格。
您可依循對您展示如何使用 DynamoDB 動作 來建立及測試規則的教學課程。如需詳細資訊，請參閱[教學課程：將裝置資料儲存在 DynamoDB 表格中](iot-ddb-rule.md)。
**注意**
此規則會以二進位資料形式將非 JSON 資料寫入 DynamoDB 中。DynamoDB 主控台會以 Base64 編碼文字來顯示資料。
## 要求
此規則動作具有下列需求：
+ AWS IoT 可以擔任以執行`dynamodb:PutItem`操作的 IAM 角色。如需詳細資訊，請參閱[授予 AWS IoT 規則所需的存取權](iot-create-role.md)。
在 AWS IoT 主控台中，您可以選擇或建立角色， AWS IoT 以允許 執行此規則動作。
+ 如果您使用客戶受管 AWS KMS key (KMS 金鑰） 來加密 DynamoDB 中的靜態資料，則服務必須具有代表發起人使用 KMS 金鑰的許可。如需詳細資訊，請參閱《Amazon DynamoDB 入門指南》**中的[客戶管理 KMS 金鑰](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/encryption.howitworks.html#managed-cmk-customer-managed)。
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
`tableName`
DynamoDB 資料表的名稱。
僅支援[替代範本](iot-substitution-templates.md)：API 和 AWS CLI
`hashKeyField`
雜湊索引鍵 (也稱為分割區索引鍵) 的名稱。
僅支援[替代範本](iot-substitution-templates.md)：API 和 AWS CLI
`hashKeyType`
(選用) 雜湊索引鍵 (也稱為分割區索引鍵) 的資料類型。有效值：`STRING`、`NUMBER`。
僅支援[替代範本](iot-substitution-templates.md)：API 和 AWS CLI
`hashKeyValue`
雜湊索引鍵的值。考慮使用替代範本，例如 `${topic()}` 或 `${timestamp()}`。
支援[替代範本](iot-substitution-templates.md)：是
`rangeKeyField`
(選用) 範圍索引鍵 (亦稱為排序索引鍵) 的名稱。
僅支援[替代範本](iot-substitution-templates.md)：API 和 AWS CLI
`rangeKeyType`
(選用) 範圍索引鍵 (亦稱為排序索引鍵) 的資料類型。有效值：`STRING`、`NUMBER`。
AWS CLI 僅支援[替代範本](iot-substitution-templates.md)：API 和
`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 範例會在 AWS IoT 規則中定義 DynamoDB 動作。
```
{
"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 開發人員指南》**中的[什麼是 Amazon DynamoDB？](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/)
+ 《Amazon DynamoDB 開發人員指南》**中的 [DynamoDB 入門](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html)
+ [教學課程：將裝置資料儲存在 DynamoDB 表格中](iot-ddb-rule.md)
# DynamoDBv2
DynamoDBv2 (`dynamoDBv2`) 動作會將 MQTT 訊息的全部或部分寫入 Amazon DynamoDB 表格。承載中的每個屬性都會寫入 DynamoDB 資料庫中不同的欄。
## 要求
此規則動作具有下列需求：
+ AWS IoT 可以擔任以執行`dynamodb:PutItem`操作的 IAM 角色。如需詳細資訊，請參閱[授予 AWS IoT 規則所需的存取權](iot-create-role.md)。
在 AWS IoT 主控台中，您可以選擇或建立角色， AWS IoT 以允許 執行此規則動作。
+ MQTT 訊息承載一定要包含一個與該表格主要分割區索引鍵相符的根層級索引鍵，以及一個與該表格的主要排序索引鍵相符的根層級索引鍵 (若有定義)。
+ 如果您使用客戶受管 AWS KMS key (KMS 金鑰） 來加密 DynamoDB 中的靜態資料，則服務必須具有代表發起人使用 KMS 金鑰的許可。如需詳細資訊，請參閱《Amazon DynamoDB 入門指南》**中的[客戶管理 KMS 金鑰](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/encryption.howitworks.html#managed-cmk-customer-managed)。
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
`putItem`
指定訊息資料將寫入的 DynamoDB 表格物件。此物件必須包含下列資訊：
`tableName`
DynamoDB 資料表的名稱。
僅支援[替代範本](iot-substitution-templates.md)：API 和 AWS CLI
`roleARN`
允許存取 DynamoDB 資料表的 IAM 角色。如需詳細資訊，請參閱[要求](#dynamodb-v2-rule-action-requirements)。
支援[替代範本](iot-substitution-templates.md)：否
寫入 DynamoDB 表格的資料產自於規則的 SQL 陳述式。
## 範例
下列 JSON 範例會在 AWS IoT 規則中定義 DynamoDBv2 動作。
```
{
"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 範例使用 AWS IoT 規則中的替代範本來定義 DynamoDB 動作。
```
{
"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 開發人員指南》**中的[什麼是 Amazon DynamoDB？](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/)
+ 《Amazon DynamoDB 開發人員指南》**中的 [DynamoDB 入門](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html)
# Elasticsearch
Elasticsearch (`elasticsearch`) 動作將資料從 MQTT 訊息寫入 Amazon OpenSearch Service 網域。您可於之後使用如 OpenSearch 儀表板等工具來查詢及視覺化 OpenSearch 中的資料。
**警告**
`Elasticsearch` 動作只能由現有規則動作使用。若要建立新的規則動作或更新現有的規則動作，請改用 `OpenSearch` 規則動作。如需詳細資訊，請參閱[OpenSearch](opensearch-rule-action.md)。
## 需求
此規則動作具有下列需求：
+ AWS IoT 可以擔任以執行`es:ESHttpPut`操作的 IAM 角色。如需詳細資訊，請參閱[授予 AWS IoT 規則所需的存取權](iot-create-role.md)。
在 AWS IoT 主控台中，您可以選擇或建立角色， AWS IoT 以允許 執行此規則動作。
+ 如果您使用客戶受管 AWS KMS key (KMS 金鑰） 來加密 OpenSearch 中的靜態資料，則服務必須具有代表發起人使用 KMS 金鑰的許可。如需詳細資訊，請參閱 *《Amazon OpenSearch Service 開發人員指南》* 中 [Amazon OpenSearch Service 的靜態資料加密](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/encryption-at-rest.html)。
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
`endpoint`
您的服務網域端點。
僅支援[替代範本](iot-substitution-templates.md)：API 和 AWS CLI
`index`
您想儲存資料的索引。
支援[替代範本](iot-substitution-templates.md)：是
`type`
欲存放文件的類型。
支援[替代範本](iot-substitution-templates.md)：是
`id`
各文件的專屬識別符。
支援[替代範本](iot-substitution-templates.md)：是
`roleARN`
IAM 角色，允許存取 OpenSearch Service 網域。如需詳細資訊，請參閱[需求](#elasticsearch-rule-action-requirements)。
支援[替代範本](iot-substitution-templates.md)：否
## 範例
下列 JSON 範例定義 AWS IoT 規則中的 Elasticsearch 動作，以及如何指定`elasticsearch`動作的欄位。如需詳細資訊，請參閱 [ElasticsearchAction](https://docs.aws.amazon.com/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 範例使用 AWS IoT 規則中的替代範本來定義 Elasticsearch 動作。
```
{
"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)
+ [什麼是 Amazon OpenSearch Service？](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/)
# HTTP
HTTPS (`http`) 動作會將資料從 MQTT 訊息傳送至 HTTPS 端點，該端點可以指向 Web 應用程式或服務。
## 要求
此規則動作具有下列需求：
+ 您必須先確認並啟用 HTTPS 端點，才可讓規則引擎使用它們。如需詳細資訊，請參閱[HTTP 動作目的地](http-action-destination.md)。
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
`url`
使用 HTTP POST 方法傳送訊息的 HTTPS 端點。若您使用 IP 地址取代主機名稱，其必須為 IPv4 地址。不支援 IPv6 地址。
支援[替代範本](iot-substitution-templates.md)：是
`confirmationUrl`
（選用） 如果指定， AWS IoT 會使用確認 URL 來建立相符的主題規則目的地。您必須先啟用 HTTP 動作目的地，才能在 HTTP 動作中使用它。如需詳細資訊，請參閱[HTTP 動作目的地](http-action-destination.md)。如果您使用替代範本，您必須先手動建立 HTTP 動作目的地，才能使用 `http`動作。 `confirmationUrl`必須是 的字首`url`。
`url` 與 `confirmationUrl` 之間的關係如下所述：
+ 如果 `url` 為硬式編碼`confirmationUrl`且未提供，我們會隱含地將 `url` 欄位視為 `confirmationUrl`。 會 AWS IoT 建立 的主題規則目的地`url`。
+ 如果 `url`和 `confirmationUrl`為硬式編碼， `url`必須以 開頭`confirmationUrl`。 會 AWS IoT 建立 的主題規則目的地`confirmationUrl`。
+ 如果 `url` 包含替代範本，則您必須指定 `confirmationUrl` 且 `url` 必須以 `confirmationUrl` 開頭。如果 `confirmationUrl`包含替代範本，您必須先手動建立 HTTP 動作目的地，才能使用 `http`動作。如果 `confirmationUrl` 不包含替代範本， 會為 AWS IoT 建立主題規則目的地`confirmationUrl`。
支援[替代範本](iot-substitution-templates.md)：是
`headers`
(選用) 要包含於端點之 HTTP 請求中的標頭清單。每個標頭必須包含下列資訊：
`key`
標頭的金鑰。
支援[替代範本](iot-substitution-templates.md)：否
`value`
標頭的值。
支援[替代範本](iot-substitution-templates.md)：是
當承載採用 JSON 格式時，預設內容類型為 application/json。否則，它是 application/octet-stream。您可以在標頭中使用重要的 content-type 指定確切的內容類型 (不區分大小寫) 來覆寫它。
`auth`
(選用) 規則引擎用來連線至 `url` 引數中所指定端點 URL 的身分驗證。目前，Signature 第 4 版是唯一支援的身分驗證類型。如需詳細資訊，請參閱 [HTTP 授權](https://docs.aws.amazon.com/iot/latest/apireference/API_HttpAuthorization.html)。
支援[替代範本](iot-substitution-templates.md)：否
`enableBatching`
（選用） 是否將 HTTP 動作訊息處理為特定 URL 的單一請求。值可以是 true 或 false。如需批次處理的詳細資訊，請參閱[批次處理 HTTP 動作訊息](http_batching.md)。
布林值
支援[替代範本](iot-substitution-templates.md)：否
`batchConfig`
（選用） 批次處理的組態設定。啟用後，必須指定`batchConfig`參數。如果未指定`batchConfig`參數，則會使用預設值。
`maxBatchOpenMs`
傳出訊息等待其他訊息建立批次的時間上限 （以毫秒為單位）。設定越高，批次 HTTP 動作的延遲就越長。
最小值：5 毫秒。最大值：200 毫秒。
預設值：20 ms
支援[替代範本](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。您可以在標頭中使用重要的 content-type 指定確切的內容類型 (不區分大小寫) 來覆寫它。
## 範例
下列 JSON 範例使用 HTTP 動作定義 AWS IoT 規則。
```
{
"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 動作重試邏輯
AWS IoT 規則引擎會根據這些規則重試 HTTP 動作：
+ 規則引擎會嘗試傳送訊息至少一次。
+ 規則引擎最多重試兩次。嘗試次數上限為三次。
+ 在下列情況下，規則引擎不會嘗試重試：
+ 上一次嘗試提供了大於 16,384 個位元組的回應。
+ 下游 Web 服務或應用程式在嘗試之後關閉 TCP 連線。
+ 完成請求的總時間超過請求逾時限制。
+ 請求傳回了 429、500-599 以外的 HTTP 狀態碼。
**注意**
[標準資料傳輸成本](https://aws.amazon.com/ec2/pricing/on-demand/)適用於重試。
## 另請參閱
+ [批次處理 HTTP 動作訊息](http_batching.md)
+ [HTTP 動作目的地](http-action-destination.md)
+ 部落格*上的物聯網 AWS*將[資料直接從 路由 AWS IoT Core 到您的 Web 服務](https://aws.amazon.com/blogs/iot/route-data-directly-from-iot-core-to-your-web-services/)
# 批次處理 HTTP 動作訊息
您可以使用批次處理在單一請求中傳送多個 HTTP 動作訊息。
## 概觀
批次處理可讓您將訊息從 AWS IoT Core 規則引擎批次傳送至 HTTP 端點。此功能可以透過減少 HTTP 動作執行的數量來協助降低成本，並透過減少與建立新連線相關的額外負荷來提高效率。
**注意**
批次 HTTP 動作會計量為單一動作。根據 AWS IoT Core 規則引擎對下游服務發出的傳出批次承載大小，以 5 kiB 的增量計量。如需詳細資訊，請參閱 [AWS IoT Core 定價頁面](https://aws.amazon.com/iot-core/pricing/)。
當您在 IoT 規則動作的定義中啟用批次處理時，下列參數將可用於組態：
`maxBatchOpenMs`
傳出訊息等待其他訊息建立批次的時間上限 （以毫秒為單位）。設定越高，批次 HTTP 動作的延遲就越長。
最小值：5 毫秒。最大值：200 毫秒。
預設值：20 ms
支援[替代範本](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
},
...
]
```
## 限制
以下是批次處理的限制：
+ AWS IoT Core 不保證整體訊息排序。批次處理會在每個主機本機執行，這可能會導致批次內的訊息處理順序與收到的順序不同。
+ AWS IoT Core 不提供接收者端的訊息處理支援。您有責任確保您的下游服務設定為接受並批次處理資料。
+ 即使訊息目的地為相同的資源識別符 (HTTP URL 或資源 ARN)，也不支援跨帳戶批次處理。
+ AWS IoT Core 不保證批次大小符合您指定的組態。根據時間和訊息流程，批次可能小於您設定的限制。
+ 啟用批次處理時，不支援二進位承載 （非 UTF-8 資料）。只接受 UTF-8 文字承載 （例如 JSON)。若要傳送二進位資料，Base64 會在傳送至 HTTP 動作之前對其進行編碼，然後在接收端點對其進行解碼。例如，您可以使用 IoT 規則中的[編碼函數](iot-sql-functions.html#iot-function-encode)來編碼二進位承載。或者，您可以在 IoT 裝置中編碼二進位承載並將其發佈到 AWS IoT Core。
## 批次處理的錯誤動作
您將無法在錯誤動作定義中定義個別的批次邏輯。不過，如果您已在主要動作中定義批次邏輯，您的錯誤動作將支援批次處理。
當批次請求失敗時， AWS IoT Core Rules 引擎將遵循 [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 動作訊息 AWS CLI
### 使用批次處理建立或更新規則動作
1. 使用適當的 AWS CLI 命令來建立或更新規則：
+ 若要建立新的規則，請使用 [create-topic-rule](https://docs.aws.amazon.com/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.aws.amazon.com/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 服務，規則引擎可以將來自主題規則的資料路由到該服務。 AWS IoT Core 資源說明 的 Web 服務 AWS IoT。目的地資源可以由不同的規則共用。
在 AWS IoT Core 可以傳送資料到另一個 Web 服務之前，它必須確認它可以存取服務的端點。
## 概觀
HTTP 動作目的地是指支援確認 URL 和一或多個資料收集 URLs Web 服務。目的地資源包含 Web 服務的確認 URL。當您設定 HTTP 動作時，您可以指定應接收資料之端點的實際 URL，以及 Web 服務的確認 URL。在確認了您的目的地之後，主題規則會將 SQL 陳述式的結果傳送至 HTTPS 端點 (而非確認 URL)。
HTTP 動作目的地可以處於下列其中一種狀態：
ENABLED
目的地已確認，且可由規則動作使用。目的地必須處於 `ENABLED` 狀態，才能在規則中使用它。您只能啟用處於 DISABLED 狀態的目的地。
DISABLED
目的地已確認，但無法由規則動作使用。如果您想暫時防止流量傳至端點，而不必再次進行確認程序，這會很有用。您只能停用處於 ENABLED 狀態的目的地。
IN\$1PROGRESS
正在確認目的地。
ERROR
目的地確認逾時。
確認並啟用 HTTP 動作目的地之後，即可與帳戶中的任何規則搭配使用。
## 管理 HTTP 動作目的地
您可以使用下列操作來管理您的 HTTP 動作目的地。
### 建立 HTTP 動作目的地
您可以透過呼叫 `CreateTopicRuleDestination`操作或使用 AWS IoT 主控台來建立 HTTP 動作目的地。
建立目的地之後， 會將確認請求 AWS 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 動作目的地的 Amazon Resource Name (ARN)。
confirmationToken
傳送的確認字符 AWS IoT Core。範例中的字符會被截斷。您的字符將更長。您需要此字符來使用 AWS IoT Core確認目的地。
enableUrl
您瀏覽以確認主題規則目的地的 URL。
messageType
訊息的類型。
### 確認 HTTP 動作目的地
若要完成端點確認程序，如果您使用的是 AWS CLI，您必須在確認 URL 收到確認請求後執行下列步驟。
1.
**確認目的地已準備好接收訊息**
若要確認 HTTP 動作目的地已準備好接收 IoT 訊息，請在確認請求`enableUrl`中呼叫 ，或執行 `ConfirmTopicRuleDestination` API 操作並從`confirmationToken`確認請求傳遞 。
1.
**將主題規則狀態設定為已啟用**
確認目的地可以接收訊息後，您必須執行 `UpdateTopicRuleDestination` API 操作，將主題規則的狀態設定為 `ENABLED`。
如果您使用的是 AWS IoT 主控台，請複製 `confirmationToken` 並將其貼到 AWS IoT 主控台的目的地確認對話方塊中。然後，您可以啟用 主題規則。
### 傳送新的確認請求
若要啟動目的地的新確認訊息，請呼叫 `UpdateTopicRuleDestination`，並將主題規則目的地的狀態設為 `IN_PROGRESS`。
在傳送新的確認請求之後重複確認程序。
### 停用和刪除 HTTP 動作目的地
若要停用目的地，請呼叫 `UpdateTopicRuleDestination`，並將主題規則目的地的狀態設為 `DISABLED`。處於 DISABLED 狀態的主題規則可以再次啟用，無需傳送新的確認請求。
若要刪除 HTTP 動作目的地，請呼叫 `DeleteTopicRuleDestination`。
## 憑證授權機構支援
**注意**
不支援自我簽署憑證。
HTTP 動作目的地中的 HTTPS 端點支援[AWS 私有憑證授權單位和 Lets Encrypt 發行的憑證](https://www.amazontrust.com/repository/)。 [https://letsencrypt.org/certificates/](https://letsencrypt.org/certificates/)
# AWS IoT Events
AWS IoT Events (`iotEvents`) 動作會將資料從 MQTT 訊息傳送至 AWS IoT Events 輸入。
**重要**
如果承載在沒有 AWS IoT Core 的情況下傳送至 `Input attribute Key`，或者如果金鑰不在金鑰中指定的相同 JSON 路徑中，則會導致 IoT 規則失敗，並顯示錯誤 `Failed to send message to Iot Events`。
## 要求
此規則動作具有下列需求：
+ AWS IoT 可以擔任以執行`iotevents:BatchPutMessage`操作的 IAM 角色。如需詳細資訊，請參閱[授予 AWS IoT 規則所需的存取權](iot-create-role.md)。
在 AWS IoT 主控台中，您可以選擇或建立角色， AWS IoT 以允許 執行此規則動作。
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
`batchMode`
(選用) 是否將事件動作作為批次處理。預設值為 `false`。
當 `batchMode`為 `true`且規則 SQL 陳述式評估為 Array 時，透過呼叫 將每個 Array 元素傳送到 AWS IoT Events 時，都會視為個別訊息[https://docs.aws.amazon.com/iotevents/latest/apireference/API_iotevents-data_BatchPutMessage.html](https://docs.aws.amazon.com/iotevents/latest/apireference/API_iotevents-data_BatchPutMessage.html)。產生的陣列不能含有超過 10 則訊息。
如果 `batchMode` 是 `true`，您無法指定 `messageId`。
支援[替代範本](iot-substitution-templates.md)：否
`inputName`
AWS IoT Events 輸入的名稱。
AWS CLI 僅支援[替代範本](iot-substitution-templates.md)：API 和
`messageId`
（選用） 使用此項目來驗證 AWS IoT Events 偵測器只會`messageId`處理具有指定 的輸入 （訊息）。您可使用 `${newuuid()}` 替代範本，為每個請求產生一個唯一 ID。
當 `batchMode` 為 `true` 時，您無法指定 `messageId`：將會指派新的 UUID 值。
支援[替代範本](iot-substitution-templates.md)：是
`roleArn`
允許 AWS IoT 將輸入傳送至偵測器的 AWS IoT Events IAM 角色。如需詳細資訊，請參閱[要求](#iotevents-rule-action-requirements)。
支援[替代範本](iot-substitution-templates.md)：否
## 範例
下面的 JSON 範例定義 AWS IoT 規則中的 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"
}
}
]
}
}
```
## 另請參閱
+ 《 *AWS IoT Events 開發人員指南*》中的[什麼是 AWS IoT Events？](https://docs.aws.amazon.com/iotevents/latest/developerguide/)
# AWS IoT SiteWise
AWS IoT SiteWise (`iotSiteWise`) 動作會將資料從 MQTT 訊息傳送至其中的資產屬性 AWS IoT SiteWise。
您可以遵循教學課程，示範如何從 AWS IoT 物件擷取資料。如需詳細資訊，請參閱*AWS IoT SiteWise 《 使用者指南*》中的[從 AWS IoT 實物教學課程擷取資料至 AWS IoT SiteWise](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/ingest-data-from-iot-things.html) ，[或使用 AWS IoT 核心規則擷取資料](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/iot-rules.html)一節。
## 要求
此規則動作具有下列需求：
+ AWS IoT 可以擔任以執行`iotsitewise:BatchPutAssetPropertyValue`操作的 IAM 角色。如需詳細資訊，請參閱[授予 AWS IoT 規則所需的存取權](iot-create-role.md)。
您可連接下列範例信任政策至該角色。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*"
}
]
}
```
若要改善安全性，您可以在 `Condition` 屬性中指定 AWS 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/*"
]
}
}
}
]
}
```
+ 當您 AWS IoT SiteWise 使用此動作將資料傳送至 時，您的資料必須符合 `BatchPutAssetPropertyValue`操作的要求。如需詳細資訊，請參閱《AWS IoT SiteWise API 參考》**中的 [BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html)。
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
`putAssetPropertyValueEntries`
資產屬性值項目的清單，其中每個項目都包含下列資訊：
`propertyAlias`
(選用) 與資產屬性相關聯的屬性別名。指定 `propertyAlias` 或同時指定 `assetId` 和 `propertyId`。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的[將工業資料串流映射至資產屬性](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/connect-data-streams.html)。
支援[替代範本](iot-substitution-templates.md)：是
`assetId`
（選用） AWS 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 epoch 時間中時間 (以秒為單位) 的字串。如果您的消息承載沒有時間戳記，可以使用 [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 epoch 時間， 僅 AWS 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`
授予 AWS IoT 許可的 IAM 角色 ARN，可將資產屬性值傳送至該角色 AWS IoT SiteWise。如需詳細資訊，請參閱[要求](#iotsitewise-rule-action-requirements)。
支援[替代範本](iot-substitution-templates.md)：否
## 範例
下面的 JSON 範例定義 AWS 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 範例定義 AWS IoT 規則中的 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"
}
}
]
}
}
```
## 另請參閱
+ 《AWS IoT SiteWise 使用者指南》**中的[什麼是 AWS IoT SiteWise？](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/what-is-sitewise.html)
+ *AWS IoT SiteWise 《 使用者指南*》中的[使用 AWS IoT Core 規則擷取資料](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/iot-rules.html)
+ *AWS IoT SiteWise 《 使用者指南*》中的[AWS IoT SiteWise 從 AWS IoT 實物擷取資料至](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/ingest-data-from-iot-things.html)
+ *AWS IoT SiteWise 《 使用者指南*》中的[AWS IoT SiteWise 規則動作疑難排解](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/troubleshoot-rule.html)
# Firehose
Firehose(`firehose`) 動作會將資料從 MQTT 訊息傳送至 Amazon Data Firehose 串流。
## 要求
此規則動作具有下列需求：
+ AWS IoT 可以擔任以執行`firehose:PutRecord`操作的 IAM 角色。如需詳細資訊，請參閱[授予 AWS IoT 規則所需的存取權](iot-create-role.md)。
在 AWS IoT 主控台中，您可以選擇或建立角色， AWS IoT 以允許 執行此規則動作。
+ 如果您使用 Firehose 將資料傳送至 Amazon S3 儲存貯體，並使用受管客戶 AWS KMS key 來加密 AWS KMS Amazon S3 中的靜態資料，Firehose 必須能夠存取您的儲存貯體，並有權代表發起人使用 AWS KMS key 。如需詳細資訊，請參閱《[Amazon Data Firehose 開發人員指南》中的授予 Firehose 存取 Amazon S3 目的地](https://docs.aws.amazon.com/firehose/latest/dev/controlling-access.html#using-iam-s3)的權限。 **
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
`batchMode`
（選用） 是否使用 以批次方式交付 Firehose [https://docs.aws.amazon.com/firehose/latest/APIReference/API_PutRecordBatch.html](https://docs.aws.amazon.com/firehose/latest/APIReference/API_PutRecordBatch.html) 串流。預設值為 `false`。
若 `batchMode` 為 `true` 且規則的 SQL 陳述式評估為 Array，則每個 Array 元會在 `PutRecordBatch` 請求中形成一筆記錄。產生的陣列不能含有超過 500 條記錄。
支援[替代範本](iot-substitution-templates.md)：否
`deliveryStreamName`
要寫入訊息資料的 Firehose 串流。
僅支援[替代範本](iot-substitution-templates.md)：API 和 AWS CLI
`separator`
（選用） 字元分隔符號，用於分隔寫入 Firehose 串流的記錄。若您略過此參數，則串流不會使用分隔符號。有效值：`,`(逗號)、`\t` (索引標籤)、`\n` (換行符號)，`\r\n` (Windows 換行)。
支援[替代範本](iot-substitution-templates.md)：否
`roleArn`
允許存取 Firehose 串流的 IAM 角色。如需詳細資訊，請參閱[要求](#kinesis-firehose-rule-action-requirements)。
支援[替代範本](iot-substitution-templates.md)：否
## 範例
下列 JSON 範例定義 AWS IoT 規則中的 Firehose 動作。
```
{
"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 範例使用 AWS IoT 規則中的替代範本來定義 Firehose 動作。
```
{
"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 開發人員指南》中的什麼是](https://docs.aws.amazon.com/firehose/latest/dev/) *Amazon Data Firehose*？
# Kinesis Data Streams
Kinesis Data Streams (`kinesis`) 動作 會將資料從 MQTT 訊息寫入 Amazon Kinesis Data Streams。
## 要求
此規則動作具有下列需求：
+ AWS IoT 可以擔任以執行`kinesis:PutRecord`操作的 IAM 角色。如需詳細資訊，請參閱[授予 AWS IoT 規則所需的存取權](iot-create-role.md)。
在 AWS IoT 主控台中，您可以選擇或建立角色， AWS IoT 以允許 執行此規則動作。
+ 如果您使用 AWS KMS 客戶受管 AWS KMS key (KMS 金鑰） 來加密 Kinesis Data Streams 中的靜態資料，則服務必須具有代表發起人使用 AWS KMS key 的許可。如需詳細資訊，請參閱《Amazon Kinesis Data Streams 開發人員指南》**中[使用使用者產生之 AWS KMS keys的許可](https://docs.aws.amazon.com/streams/latest/dev/permissions-user-key-KMS.html)。
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
`stream`
要寫入資料的 Kinesis 資料串流。
僅支援[替代範本](iot-substitution-templates.md)：API 和 AWS CLI
`partitionKey`
分割區索引鍵用來決定資料要寫入哪個碎片。分割區索引鍵通常是由表達式 (如 `${topic()}` 或 `${timestamp()}`) 組成。
支援[替代範本](iot-substitution-templates.md)：是
`roleArn`
授予存取 Kinesis 資料串流 AWS IoT 許可的 IAM 角色 ARN。如需詳細資訊，請參閱[要求](#kinesis-rule-action-requirements)。
支援[替代範本](iot-substitution-templates.md)：否
## 範例
下列 JSON 範例定義 AWS IoT 規則中的 Kinesis Data Streams 動作。
```
{
"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 範例使用 AWS IoT 規則中的替代範本來定義 Kinesis 動作。
```
{
"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.aws.amazon.com/streams/latest/dev/)
# Lambda
Lambda (`lambda`) 動作會叫用 AWS Lambda 函數，以非同步方式傳入 MQTT 訊息。 AWS IoT 叫用 Lambda 函數。
您可依循對您展示如何使用 Lambda 動作 來建立及測試規則的教學課程。如需詳細資訊，請參閱[教學課程：使用 AWS Lambda 函數格式化通知](iot-lambda-rule.md)。
## 需求
此規則動作具有下列需求：
+ 若要 AWS IoT 讓 叫用 Lambda 函數，您必須設定授予 `lambda:InvokeFunction`許可的政策 AWS IoT。您只能叫用 Lambda 政策存在 AWS 區域 的相同 中定義的 Lambda 函數。Lambda 函數使用的是資源型政策，因此您必須將政策連接至 Lambda 函數本身。
使用下列 AWS CLI 命令來連接授予 `lambda:InvokeFunction`許可的政策。在此命令中，取代：
+ *function\$1name* 與 Lambda 函數的名稱。您可以新增許可來更新函數的資源政策。
+ 具有 函數 AWS 區域 之 *的區域*。
+ *account-id*，其中包含定義規則的 AWS 帳戶 數字。
+ *rule-name*，其中包含您定義 Lambda 動作之 AWS IoT 規則的名稱。
+ *unique\$1id* 具有唯一的陳述式識別符。
**重要**
如果您為 AWS IoT 委託人新增許可，但未提供 `source-arn`或 `source-account`，則任何使用 Lambda 動作建立規則 AWS 帳戶 的 都可以啟用規則來叫用您的 Lambda 函數 AWS IoT。
如需詳細資訊，請參閱 [AWS Lambda 許可](https://docs.aws.amazon.com/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"
```
+ 如果您使用 AWS IoT 主控台為 Lambda 規則動作建立規則，則會自動觸發 Lambda 函數。如果您 AWS CloudFormation 改搭配 使用 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iot-topicrule-lambdaaction.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iot-topicrule-lambdaaction.html)，則必須新增 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-permission.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-permission.html) 資源。然後，資源會授予您觸發 Lambda 函數的許可。
下列程式碼顯示如何新增此資源的範例。在此範例中，取代：
+ *function\$1name* 與 Lambda 函數的名稱。
+ 具有 函數 AWS 區域 之 *的區域*。
+ *account-id*，其中包含定義規則的 AWS 帳戶 數字。
+ *rule-name*，其中包含您定義 Lambda 動作之 AWS 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
```
+ 如果您使用受管 AWS KMS 客戶 AWS KMS key 來加密 Lambda 中的靜態資料，服務必須具有代表發起人使用 AWS KMS key 的許可。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的[靜態加密](https://docs.aws.amazon.com/lambda/latest/dg/security-dataprotection.html#security-privacy-atrest)。
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
`functionArn`
要叫用的 Lambda 函數 ARN。 AWS IoT 必須具有叫用函數的許可。如需詳細資訊，請參閱[需求](#lambda-rule-action-requirements)。
如果您未針對您的 Lambda 函數指定版本或別名，則最新版的函數會關閉。如果想要關閉特定版本的 Lambda 函數，您可以指定版本或別名。如要指定版本或別名，請將版本或別名附加至 Lambda 函數的 ARN。
```
arn:aws:lambda:us-east-2:123456789012:function:myLambdaFunction:someAlias
```
如需版本控制與別名的詳細資訊，請參閱 [AWS Lambda 函數版本控制與別名](https://docs.aws.amazon.com/lambda/latest/dg/versioning-aliases.html)。
AWS CLI 僅支援[替代範本](iot-substitution-templates.md)：API 和
## 範例
下列 JSON 範例會在 AWS IoT 規則中定義 Lambda 動作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-east-2:123456789012:function:myLambdaFunction"
}
}
]
}
}
```
下列 JSON 範例使用 AWS IoT 規則中的替代範本來定義 Lambda 動作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-east-1:123456789012:function:${topic()}"
}
}
]
}
}
```
## 另請參閱
+ 《 *AWS Lambda 開發人員指南*》中的[什麼是 AWS Lambda？](https://docs.aws.amazon.com/lambda/latest/dg/)
+ [教學課程：使用 AWS Lambda 函數格式化通知](iot-lambda-rule.md)
# Location
Location (`location`) (位置) 動作會將您的地理位置資料傳送至 [Amazon Location Service](https://docs.aws.amazon.com//location/latest/developerguide/welcome.html)。
## 要求
此規則動作具有下列需求：
+ AWS IoT 可以擔任以執行`geo:BatchUpdateDevicePosition`操作的 IAM 角色。如需詳細資訊，請參閱[授予 AWS IoT 規則所需的存取權](iot-create-role.md)。
在 AWS IoT 主控台中，您可以選擇或建立角色，以允許 AWS IoT 執行此規則動作。
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
`deviceId`
提供位置資料的裝置唯一 ID。如需詳細資訊，請參閱《Amazon Location Service API 參考》**中的 [https://docs.aws.amazon.com//location/latest/APIReference/API_DevicePositionUpdate.html](https://docs.aws.amazon.com//location/latest/APIReference/API_DevicePositionUpdate.html)。
支援[替代範本](iot-substitution-templates.md)：是
`latitude`
此字串評估為雙精確度值，該值代表裝置位置的緯度。
支援[替代範本](iot-substitution-templates.md)：是
`longitude`
此字串評估為雙精確度值，該值代表裝置位置的經度。
支援[替代範本](iot-substitution-templates.md)：是
`roleArn`
IAM 角色，允許存取 Amazon Location Service 網域。如需詳細資訊，請參閱[要求](#location-rule-action-requirements)。
`timestamp`
對位置資料進行取樣的時間。預設值是處理 MQTT 訊息的時間。
`timestamp` 值包含以下兩個值：
+ `value`：傳回一個很長的 Epoch 時間值的表達式。您可使用 [time\$1to\$1epoch(String, String)](iot-sql-functions.md#iot-sql-function-time-to-epoch) 函數，從訊息承載中傳遞的日期或時間建立有效的時間戳記。支援[替代範本](iot-substitution-templates.md)：是。
+ `unit`：(選擇性) `value` 中所述運算式產生的 timestamp 值的精確度。有效值：`SECONDS` \$1 `MILLISECONDS` \$1 `MICROSECONDS` \$1 `NANOSECONDS`。預設值為 `MILLISECONDS`。支援[替代範本](iot-substitution-templates.md)： AWS CLI 僅限 API 和 。
`trackerName`
在已更新位置的 Amazon Location 中的追蹤器資源名稱。如需詳細資訊，請參閱《Amazon Location Service 開發人員指南》**中的[追蹤器](https://docs.aws.amazon.com//location/latest/developerguide/geofence-tracker-concepts.html#tracking-overview)。
僅支援[替代範本](iot-substitution-templates.md)：API 和 AWS CLI
## 範例
下列 JSON 範例定義 AWS 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 範例使用 AWS 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.aws.amazon.com/cli/latest/reference/location/get-device-position-history.html](https://docs.aws.amazon.com/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 開發人員指南》**中的[什麼是 Amazon Location Service？](https://docs.aws.amazon.com//location/latest/developerguide/welcome.html)。
# OpenSearch
OpenSearch (`openSearch`) 動作將資料從 MQTT 訊息寫入 Amazon OpenSearch Service 網域。您可於之後使用如 OpenSearch 儀表板等工具來查詢及視覺化 OpenSearch Service 中的資料。
## 要求
此規則動作具有下列需求：
+ AWS IoT 可以擔任以執行`es:ESHttpPut`操作的 IAM 角色。如需詳細資訊，請參閱[授予 AWS IoT 規則所需的存取權](iot-create-role.md)。
在 AWS IoT 主控台中，您可以選擇或建立角色， AWS IoT 以允許 執行此規則動作。
+ 如果您使用受管客戶 AWS KMS key 來加密 OpenSearch Service 中的靜態資料，則該服務必須具有代表發起人使用 KMS 金鑰的許可。如需詳細資訊，請參閱 *《Amazon OpenSearch Service 開發人員指南》* 中 [Amazon OpenSearch Service 的靜態資料加密](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/encryption-at-rest.html)。
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
`endpoint`
您 Amazon OpenSearch Service 網域的端點。
僅支援[替代範本](iot-substitution-templates.md)：API 和 AWS 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`
IAM 角色，允許存取 OpenSearch Service 網域。如需詳細資訊，請參閱[要求](#opensearch-rule-action-requirements)。
支援[替代範本](iot-substitution-templates.md)：否
## 限制
OpenSearch (`openSearch`）動作不能用於將資料傳送到 VPC Elasticsearch 叢集。
## 範例
下列 JSON 範例定義 AWS IoT 規則中的 OpenSearch 動作，以及如何指定`OpenSearch`動作的欄位。如需詳細資訊，請參閱 [OpenSearchAction](https://docs.aws.amazon.com/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 範例使用 AWS 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`。
## 另請參閱
[什麼是 ？*Amazon OpenSearch Service 開發人員指南* 中的Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/)
# 重新發佈
重新發佈 (`republish`) 動作將 MQTT 訊息重新發佈至另一個 MQTT 主題。
## 要求
此規則動作具有下列需求：
+ AWS IoT 可以擔任以執行`iot:Publish`操作的 IAM 角色。如需詳細資訊，請參閱[授予 AWS IoT 規則所需的存取權](iot-create-role.md)。
在 AWS IoT 主控台中，您可以選擇或建立角色， AWS IoT 以允許 執行此規則動作。
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
`headers`
MQTT 5.0 版標頭資訊。
如需詳細資訊，請參閱《AWS API 參考》** 中的 [RepublishAction](https://docs.aws.amazon.com//iot/latest/apireference/API_RepublishAction.html) 和 [MqttHeaders](https://docs.aws.amazon.com//iot/latest/apireference/API_MqttHeaders.html)。
`topic`
要將訊息重新發佈至該 MQTT 主題。
如要重新發佈至以 `$` 開頭的預留主題，請改用 `$$`。例如，如要重新發佈至裝置影子主題 `$aws/things/MyThing/shadow/update`，請將主題指定為 `$$aws/things/MyThing/shadow/update`。
重新發佈至[預留任務主題](reserved-topics.md#reserved-topics-job)不受支援。
AWS IoT Device Defender 預留主題不支援 HTTP 發佈。
支援[替代範本](iot-substitution-templates.md)：是
`qos`
(選用) 重新發佈訊息時要使用的服務品質 (QoS) 層級。有效值：`0`、`1`。預設值為 `0`。如需 MQTT QoS 的詳細資訊，請參閱 [MQTT](mqtt.md)。
支援[替代範本](iot-substitution-templates.md)：否
`roleArn`
允許 AWS IoT 發佈至 MQTT 主題的 IAM 角色。如需詳細資訊，請參閱[要求](#republish-rule-action-requirements)。
支援[替代範本](iot-substitution-templates.md)：否
## 範例
下列 JSON 範例定義 AWS 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 範例使用 AWS 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 範例定義在 AWS 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"
}
]
}
}
}
]
}
}
```
**注意**
原始來源 IP 不會透過[重新發布動作](#republish-rule-action)傳遞。
# S3
S3 (`s3`) 動作會從 MQTT 訊息將資料寫入 Amazon Simple Storage Service (Amazon S3) 儲存貯體。
## 要求
此規則動作具有下列需求：
+ AWS IoT 可以擔任以執行`s3:PutObject`操作的 IAM 角色。如需詳細資訊，請參閱[授予 AWS IoT 規則所需的存取權](iot-create-role.md)。
在 AWS IoT 主控台中，您可以選擇或建立角色， AWS IoT 以允許 執行此規則動作。
+ 如果您使用 受管 AWS KMS 客戶 AWS KMS key 來加密 Amazon S3 中的靜態資料，服務必須具有代表發起人使用 AWS KMS key 的許可。如需詳細資訊，請參閱《*Amazon Simple Storage Service 開發人員指南*》中的[AWS 受管 AWS KMS keys 和客戶受 AWS KMS keys](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html#aws-managed-customer-managed-cmks)管。
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
`bucket`
要寫入資料的 Amazon S3 儲存貯體。
僅支援[替代範本](iot-substitution-templates.md)：API 和 AWS CLI
`cannedacl`
(選用) Amazon S3 固定的 ACL，負責控制物件金鑰辨識出之物件的存取權限。如需詳細資訊 (包含允許的值)，請參閱[固定 ACL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl)。
支援[替代範本](iot-substitution-templates.md)：否
`key`
寫入資料的檔案路徑。
考慮一個範例，其中此參數為 `${topic()}/${timestamp()}`，且規則會收到主題為 `some/topic` 訊息。若目前的時間戳記為 `1460685389`，則此動作會將資料寫入在 S3 儲存貯體 `some/topic` 資料夾中名為 `1460685389` 的檔案。
如果您使用靜態金鑰， 會在每次呼叫規則時 AWS IoT 覆寫單一檔案。我們建議您使用訊息時間戳記或另一個唯一的訊息識別符，以便每一個收到的訊息都會將新檔案儲存於 Amazon S3 中。
支援[替代範本](iot-substitution-templates.md)：是
`roleArn`
允許存取 Amazon S3 儲存貯體的 IAM 角色。如需詳細資訊，請參閱[要求](#s3-rule-action-requirements)。
支援[替代範本](iot-substitution-templates.md)：否
## 範例
下列 JSON 範例定義 AWS 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.aws.amazon.com/AmazonS3/latest/userguide/)
# Salesforce IoT
Salesforce IoT (`salesforce`) 動作將資料從觸發規則的 MQTT 訊息傳送至 Salesforce IoT 輸入串流。
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
`url`
該 URL 會透過 Salesforce IoT 輸入串流公開。在您建立輸入串流時，便可從 Salesforce IoT 平台使用 URL。若需詳細資訊，請參閱 Salesforce IoT 文件。
支援[替代範本](iot-substitution-templates.md)：否
`token`
用於驗證特定 Salesforce IoT 輸入串流存取的權杖。在您建立輸入串流時，您便可在 Salesforce IoT 平台使用權杖。若需詳細資訊，請參閱 Salesforce IoT 文件。
支援[替代範本](iot-substitution-templates.md)：否
## 範例
下面的 JSON 範例定義 AWS IoT 規則中的 Salesforce IoT 動作。
```
{
"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.aws.amazon.com/sns/latest/dg/sns-fifo-topics.html)。因為規則引擎是一項完全分配式的服務，因此在呼叫 SNS 動作時無法保證訊息順序。
## 要求
此規則動作具有下列需求：
+ AWS IoT 可以擔任以執行`sns:Publish`操作的 IAM 角色。如需詳細資訊，請參閱[授予 AWS IoT 規則所需的存取權](iot-create-role.md)。
在 AWS IoT 主控台中，您可以選擇或建立角色， AWS IoT 以允許 執行此規則動作。
+ 如果您使用 AWS KMS 客戶受管 AWS KMS key 來加密 Amazon SNS 中的靜態資料，則服務必須具有代表發起人使用 AWS KMS key 的許可。如需詳細資訊，請參閱《Amazon Simple Notification Service 開發人員指南》**中的[金鑰管理](https://docs.aws.amazon.com/sns/latest/dg/sns-key-management.html)。
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
`targetArn`
推送通知傳送到的 SNS 主題或個別裝置。
AWS CLI 僅支援[替代範本](iot-substitution-templates.md)：API 和
`messageFormat`
(選用) 訊息格式。Amazon SNS 會使用此設定來判斷是否應剖析承載，以及是否應擷取承載與特定平台相關的部分。有效值：`JSON`、`RAW`。預設為 `RAW`。
支援[替代範本](iot-substitution-templates.md)：否
`roleArn`
允許存取 SNS 的 IAM 角色。如需詳細資訊，請參閱[要求](#sns-rule-action-requirements)。
支援[替代範本](iot-substitution-templates.md)：否
## 範例
下列 JSON 範例定義 AWS IoT 規則中的 SNS 動作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:us-east-2:123456789012:my_sns_topic",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sns"
}
}
]
}
}
```
下列 JSON 範例使用 AWS 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.aws.amazon.com/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.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues.html)。因為規則引擎是一項完全分配式的服務，因此在觸發 SQS 動作時無法保證訊息順序。
## 要求
此規則動作具有下列需求：
+ AWS IoT 可以擔任以執行`sqs:SendMessage`操作的 IAM 角色。如需詳細資訊，請參閱[授予 AWS IoT 規則所需的存取權](iot-create-role.md)。
在 AWS IoT 主控台中，您可以選擇或建立角色， AWS IoT 以允許 執行此規則動作。
+ 如果您使用受管 AWS KMS 客戶 AWS KMS key 來加密 Amazon SQS 中的靜態資料，則服務必須具有代表發起人使用 AWS KMS key 的許可。如需詳細資訊，請參閱《Amazon Simple Queue Service 開發人員指南》**中的[金鑰管理](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-key-management.html)。
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
`queueUrl`
要寫入資料的 Amazon SQS 佇列 URL。此 URL 中的區域不需要與您的[AWS IoT 規則](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html) AWS 區域 相同。
AWS 區域 使用 SQS 規則動作進行跨資料傳輸可能會產生額外費用。如需詳細資訊，請參閱 [Amazon SQS 定價](https://aws.amazon.com/sqs/pricing/)。
AWS CLI 僅支援[替代範本](iot-substitution-templates.md)：API 和
`useBase64`
設定此參數為 `true` 以配置規則動作，在資料寫入 Amazon SQS 佇列之前，對訊息資料進行 base64 編碼。預設為 `false`。
支援[替代範本](iot-substitution-templates.md)：否
`roleArn`
允許存取 Amazon SQS 佇列的 IAM 角色。如需詳細資訊，請參閱[要求](#sqs-rule-action-requirements)。
支援[替代範本](iot-substitution-templates.md)：否
## 範例
下列 JSON 範例定義 AWS 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 範例使用 AWS 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.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/)
# 步驟函數
Step Functions (`stepFunctions`) 動作會啟動 AWS Step Functions 狀態機器。
## 要求
此規則動作具有下列需求：
+ AWS IoT 可以擔任以執行`states:StartExecution`操作的 IAM 角色。如需詳細資訊，請參閱[授予 AWS IoT 規則所需的存取權](iot-create-role.md)。
在 AWS IoT 主控台中，您可以選擇或建立角色， AWS IoT 以允許 執行此規則動作。
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
`stateMachineName`
要啟動的 Step Functions 狀態機器名稱。
僅支援[替代範本](iot-substitution-templates.md)：API 和 AWS CLI
`executionNamePrefix`
(選用) 狀態機器執行的名稱，包含此字首後接 UUID。若未提供名稱，Step Functions 會為每個狀態機器建立一個唯一的名稱。
支援[替代範本](iot-substitution-templates.md)：是
`roleArn`
授予啟動狀態機器 AWS IoT 許可之角色的 ARN。如需詳細資訊，請參閱[要求](#stepfunctions-rule-action-requirements)。
支援[替代範本](iot-substitution-templates.md)：否
## 範例
下列 JSON 範例定義 AWS 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"
}
}
]
}
}
```
## 另請參閱
+ 《 *AWS Step Functions 開發人員指南*》中的[什麼是 AWS Step Functions？](https://docs.aws.amazon.com/step-functions/latest/dg/)
# Timestream
Timestream 規則動作將屬性 (測量) 從 MQTT 訊息寫入 Amazon Timestream 表格中。如需 Amazon Timestream 的詳細資訊，請參閱[什麼是 Amazon Timestream？](https://docs.aws.amazon.com/timestream/latest/developerguide/what-is-timestream.html)。
**注意**
並非所有 AWS 區域都提供 Amazon Timestream。若 Amazon Timestream 無法在您的區域中使用，則不會顯示於規則動作清單中。
此規則儲存於 Timestream 資料庫中的屬性是規則查詢陳述式所產生的屬性。剖析查詢陳述式結果中每個屬性值，以推斷其資料類型 (如 [DynamoDBv2](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)。
**注意**
可以寫入 Amazon Timestream 表格的最大 Timestream 規則動作值為 100。如需詳細資訊，請參閱 [Amazon Timestream 配額參考](https://docs.aws.amazon.com//timestream/latest/developerguide/ts-limits.html#limits.default)。
## 要求
此規則動作具有下列需求：
+ AWS IoT 可以擔任以執行 `timestream:DescribeEndpoints`和 `timestream:WriteRecords`操作的 IAM 角色。如需詳細資訊，請參閱[授予 AWS IoT 規則所需的存取權](iot-create-role.md)。
在 AWS IoT 主控台中，您可以選擇、更新或建立角色， AWS IoT 以允許 執行此規則動作。
+ 如果您使用客戶 AWS KMS 加密 Timestream 中的靜態資料，服務必須具有代表發起人使用 AWS KMS key 的許可。如需詳細資訊，請參閱 [AWS 服務如何使用 AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/service-integration.html)。
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
`databaseName`
Amazon Timestream 資料庫的名稱，其中包含用於接收此動作所建立之記錄的資料表。另請參閱`tableName`。
僅支援[替代範本](iot-substitution-templates.md)：API 和 AWS CLI
`dimensions`
寫入每個量測記錄的時間序列的中繼資料屬性。例如，EC2 執行個體的名稱和可用區域，或風力發電機製造商的名稱即為維度。
`name`
中繼資料維度名稱。這是資料庫資料表記錄中的欄的名稱。
無法命名的維度：`measure_name`、`measure_value`, 或 `time`。這些為預留名稱。維度名稱不可以 `ts_` 或 `measure_value` 開頭，且其不可包含冒號 (`:`) 字元。
支援[替代範本](iot-substitution-templates.md)：否
`value`
要寫入資料庫記錄的該資料欄的值。
支援[替代範本](iot-substitution-templates.md)：是
`roleArn`
授予 AWS IoT 許可之角色的 Amazon 資源名稱 (ARN)，可寫入 Timestream 資料庫表格。如需詳細資訊，請參閱[要求](#timestream-rule-action-requirements)。
支援[替代範本](iot-substitution-templates.md)：否
`tableName`
要寫入測量記錄的資料庫表格名稱。另請參閱`databaseName`。
僅支援[替代範本](iot-substitution-templates.md)：API 和 AWS CLI
`timestamp`
要用於項目的 timestamp 的值。若為空白，則會使用處理項目的時間。
`unit`
`value` 中所述運算式產生的 timestamp 值的精確度。
有效值：`SECONDS` \$1 `MILLISECONDS` \$1 `MICROSECONDS` \$1 `NANOSECONDS`。預設值為 `MILLISECONDS`。
`value`
傳回一個很長的 Epoch 時間值的表達式。
您可使用 [time\$1to\$1epoch(String, String)](iot-sql-functions.md#iot-sql-function-time-to-epoch) 函數，從訊息承載中傳遞的日期或時間建立有效的時間戳記。
## Timestream 記錄內容
此動作寫入 Amazon Timestream 表格的資料包括時間戳記、來自 Timestream 規則動作的中繼資料，及規則查詢陳述式的結果。
對於查詢陳述式結果中的每個屬性 (測量)，此規則動作會將記錄寫入具有這些欄的指定 Timestream 表格。
| 欄名稱 | 屬性類型 | Value | 說明 |
| --- | --- | --- | --- |
| *dimension-name* | DIMENSION | 指定於 Timestream 規則動作項目中的值。 | 指定於規則動作項目中的每個**維度**都會於 Timestream 資料庫中建立一個具維度名稱的欄。 |
| measure\$1name | MEASURE\$1NAME | 屬性名稱 | 查詢陳述式結果中的屬性名稱，其值指定於 `measure_value::data-type` 欄中。 |
| measure\$1value::*data-type* | MEASURE\$1VALUE | 查詢陳述式結果中的屬性值。屬性名稱位於 `measure_name` 欄中。 | 此值會進行解譯\$1 並轉換為最適合下列的比對項目：`bigint`、`boolean`、`double` 或 `varchar`。Amazon Timestream 為每種資料類型建立一個個別的欄。訊息中的值可使用規則查詢陳述式中的 [`cast()`](iot-sql-functions.md#iot-sql-function-cast) 函數轉換為另一個資料。 |
| time | TIMESTAMP | 資料庫中記錄的日期和時間。 | 此值是由規則引擎或 `timestamp` 屬性來指派 (若已定義)。 |
\$1 從訊息承載讀取的屬性值解譯如下。請參閱 [範例](#timestream-rule-action-examples)，以取得每個案例的說明。
+ 將 `true` 或 `false` 的未加引號值解釋為 `boolean` 類型。
+ 將十進位數字解釋為 `double` 類型。
+ 將未帶小數點的十進位數值解釋為 `bigint` 類型。
+ 將帶引號的字串解釋為 `varchar` 類型。
+ 將物件和陣列數值轉換為 JSON 字串並儲存為 `varchar` 類型。
## 範例
下列 JSON 範例使用 規則中的替代範本來定義 Timestream AWS 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` 欄為定義於主題規則動作中的 DIMENSIONS (維度)。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 | time |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 我的靜態中繼資料 | iotconsole-159EXAMPLE738-0 | complex\$1value | - | \$1"simple\$1element":42,"array\$1of\$1integers":[23,36,56,72],"字串陣列":["紅","綠","藍"]\$1 | - | - | 2020-08-26 22:42:16.423000000 |
| 我的靜態中繼資料 | iotconsole-159EXAMPLE738-0 | integer\$1value\$1as\$1string | - | 123456789012 | - | - | 2020-08-26 22:42:16.423000000 |
| 我的靜態中繼資料 | iotconsole-159EXAMPLE738-0 | boolean\$1value | - | - | - | TRUE | 2020-08-26 22:42:16.423000000 |
| 我的靜態中繼資料 | iotconsole-159EXAMPLE738-0 | integer\$1value | 123456789012 | - | - | - | 2020-08-26 22:42:16.423000000 |
| 我的靜態中繼資料 | iotconsole-159EXAMPLE738-0 | string\$1value | - | 字串值 | - | - | 2020-08-26 22:42:16.423000000 |
| 我的靜態中繼資料 | iotconsole-159EXAMPLE738-0 | array\$1of\$1integers | - | [23,36,56,72] | - | - | 2020-08-26 22:42:16.423000000 |
| 我的靜態中繼資料 | iotconsole-159EXAMPLE738-0 | 字串陣列 | - | ["紅","綠","藍"] | - | - | 2020-08-26 22:42:16.423000000 |
| 我的靜態中繼資料 | iotconsole-159EXAMPLE738-0 | boolean\$1value\$1as\$1string | - | TRUE | - | - | 2020-08-26 22:42:16.423000000 |
| 我的靜態中繼資料 | iotconsole-159EXAMPLE738-0 | double\$1value | - | - | 123.456789012 | - | 2020-08-26 22:42:16.423000000 |
| 我的靜態中繼資料 | iotconsole-159EXAMPLE738-0 | double\$1value\$1as\$1string | - | 123.45679 | - | - | 2020-08-26 22:42:16.423000000 |
## 規則疑難排解
如果您遇到規則方面的問題，建議您啟動 CloudWatch Logs。您可分析您的記錄，即可判斷該問題是否在於授權，或者是否為 WHERE 子句條件不相符之類的問題。如需詳細資訊，請參閱[設定 CloudWatch Logs](https://docs.aws.amazon.com/iot/latest/developerguide/cloud-watch-logs.html)。
# 使用 AWS IoT 規則存取跨帳戶資源
您可以設定跨帳戶存取的 AWS IoT 規則，以便將某個帳戶的 MQTT 主題擷取的資料路由到另一個帳戶的 AWS 服務，例如 Amazon SQS 和 Lambda。以下說明如何設定跨帳戶資料擷取的 AWS IoT 規則，從一個帳戶中的 MQTT 主題，到另一個帳戶中的目的地。
跨帳戶規則可使用[資源型許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html#TypesPermissions)，在目的地資源上進行配至。因此，只有支援資源型許可的目的地才能使用 AWS IoT 規則啟用跨帳戶存取。支援的目的地包括 Amazon SQS、Amazon SNS、Amazon S3 和 AWS Lambda。
**注意**
對於支援的目的地，除了 Amazon SQS 之外，您必須在與其他服務資源 AWS 區域 相同的 中定義規則，以便規則動作可以與該資源互動。如需 AWS IoT 規則動作的詳細資訊，請參閱[AWS IoT 規則動作](iot-rule-actions.md)。如需規則 SQS 動作的詳細資訊，請參閱 [SQS](sqs-rule-action.md)。
## 先決條件
+ 熟悉 [AWS IoT 規則](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html)
+ 了解 IAM [使用者](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_identity-management.html)、[角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) 和[資源型許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_permissions.html#TypesPermissions)
+ 安裝了 [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)
## Amazon SQS 的跨帳戶設定
案例：帳戶 A 將資料從 MQTT 訊息傳送至帳戶 B 的 Amazon SQS 佇列。
| AWS 帳戶 | 帳戶稱為 | Description |
| --- | --- | --- |
| 1111-1111-1111 | 帳戶 A | 規則動作：sqs:SendMessage |
| 2222-2222-2222 | 帳戶 B | Amazon SQS 佇列 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot/latest/developerguide/accessing-cross-account-resources-using-rules.html) |
**注意**
您的目的地 Amazon SQS 佇列不必 AWS 區域 與您的[AWS IoT 規則](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html)位於相同的 中。如需規則 SQS 動作的詳細資訊，請參閱 [SQS](sqs-rule-action.md)。
**執行帳戶 A 任務**
**注意**
如要執行下列命令，您的 IAM 使用者應具有以規則的 Amazon 資源名稱 (ARN) 作為資源的 `iot:CreateTopicRule` 許可，及以資源作為角色之 ARN 的 `iam:PassRole` 動作許可。
1. 使用帳戶 A 的 IAM 使用者[配置 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)。
1. 建立信任 AWS IoT 規則引擎的 IAM 角色，並連接允許存取帳戶 B Amazon SQS 佇列的政策。請參閱[授予 AWS IoT 必要存取權](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html)中的命令和政策文件範例。
1. 如要建立連接至主題的規則，請執行 [create-topic-rule 命令](https://docs.aws.amazon.com/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 授予 AWS 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
}
}
]
}
```
如需如何在 AWS IoT 規則中定義 Amazon SQS 動作的詳細資訊，請參閱[AWS IoT 規則動作 - Amazon SQS](https://docs.aws.amazon.com/iot/latest/developerguide/sqs-rule-action.html)。
**執行帳戶 B 任務**
1. 使用帳戶 B 的 IAM 使用者[配置 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)。
1. 如要將 Amazon SQS 佇列資源的許可授予帳戶 A，請執行 [add-permission 命令](https://docs.aws.amazon.com/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 主題。
| AWS 帳戶 | 帳戶稱為 | Description |
| --- | --- | --- |
| 1111-1111-1111 | 帳戶 A | 規則動作：sns:Publish |
| 2222-2222-2222 | 帳戶 B | Amazon SNS 主題 ARN：arn:aws:sns:region:2222-2222-2222:ExampleTopic |
**執行帳戶 A 任務**
**備註**
如要執行下列命令，您的 IAM 使用者應具有以規則 ARN 作為資源的 `iot:CreateTopicRule` 許可，以及資源作為角色 ARN 的 `iam:PassRole` 動作許可。
1. 使用帳戶 A 的 IAM 使用者[配置 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)。
1. 建立信任 AWS IoT 規則引擎的 IAM 角色，並連接允許存取帳戶 B 的 Amazon SNS 主題的政策。如需命令和政策文件的範例，請參閱[授予 AWS IoT 必要的存取權](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html)。
1. 如要建立連接至主題的規則，請執行 [create-topic-rule 命令](https://docs.aws.amazon.com/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 授予 AWS 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"
}
}
]
}
```
如需如何在 AWS IoT 規則中定義 Amazon SNS 動作的詳細資訊，請參閱[AWS IoT 規則動作 - Amazon SNS](https://docs.aws.amazon.com/iot/latest/developerguide/sns-rule-action.html)。
**執行帳戶 B 任務**
1. 使用帳戶 B 的 IAM 使用者[配置 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)。
1. 如要將 Amazon SNS 主題資源的許可授予帳戶 A，請執行 [add-permission 命令](https://docs.aws.amazon.com/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 儲存貯體。
| AWS 帳戶 | 帳戶稱為 | Description |
| --- | --- | --- |
| 1111-1111-1111 | 帳戶 A | 規則動作：s3:PutObject |
| 2222-2222-2222 | 帳戶 B | Amazon S3 儲存貯體 ARN：arn:aws:s3:::amzn-s3-demo-bucket |
**執行帳戶 A 任務**
**注意**
如要執行下列命令，您的 IAM 使用者應具有以規則 ARN 作為資源的 `iot:CreateTopicRule` 許可，以及資源作為角色 ARN 的 `iam:PassRole` 動作許可。
1. 使用帳戶 A 的 IAM 使用者[配置 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)。
1. 建立信任 AWS IoT 規則引擎並連接允許存取帳戶 B Amazon S3 儲存貯體的政策的 IAM 角色。如需命令和政策文件的範例，請參閱[授予 AWS IoT 必要的存取權](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html)。
1. 如要建立連接至您目標 S3 儲存貯體的規則，請執行 [create-topic-rule 命令](https://docs.aws.amazon.com/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 授予 AWS 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"
}
}
]
}
```
如需如何在 AWS IoT 規則中定義 Amazon S3 動作的詳細資訊，請參閱[AWS IoT 規則動作 - Amazon S3](https://docs.aws.amazon.com/iot/latest/developerguide/s3-rule-action.html)。
**執行帳戶 B 任務**
1. 使用帳戶 B 的 IAM 使用者[配置 AWS CLI](https://docs.aws.amazon.com/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.aws.amazon.com/AmazonS3/latest/userguide/example-bucket-policies.html#example-bucket-policies-use-case-1)。
1. 如要將儲存貯體政策連接至指定的儲存貯體，請執行 [put-bucket-policy 命令](https://docs.aws.amazon.com/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.aws.amazon.com/AmazonS3/latest/userguide/security-best-practices.html)。
## 的跨帳戶設定 AWS Lambda
案例：帳戶 A 叫用帳戶 B 的 AWS Lambda 函數，傳入 MQTT 訊息。
| AWS 帳戶 | 帳戶稱為 | Description |
| --- | --- | --- |
| 1111-1111-1111 | 帳戶 A | 規則動作：lambda:InvokeFunction |
| 2222-2222-2222 | 帳戶 B | Lambda 函數 ARN： arn:aws:lambda:region:2222-2222-2222:function:example-function |
**執行帳戶 A 任務**
**備註**
如要執行下列命令，您的 IAM 使用者應具有以規則 ARN 作為資源的 `iot:CreateTopicRule` 許可，以及資源作為角色 ARN 的 `iam:PassRole` 動作許可。
1. 使用帳戶 A 的 IAM 使用者[配置 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)。
1. 執行 [create-topic-rule 命令](https://docs.aws.amazon.com/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 授予 AWS 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"
}
}
]
}
```
如需如何在 規則中 AWS IoT 定義 AWS Lambda 動作的詳細資訊，請參閱[AWS IoT 規則動作 - Lambda](https://docs.aws.amazon.com/iot/latest/developerguide/lambda-rule-action.html)。
**執行帳戶 B 任務**
1. 使用帳戶 B 的 IAM 使用者[配置 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)。
1. 執行 [Lambda 的 add-permission 命令](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html)，給予 AWS 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**
此欄位提供 AWS IoT （由 表示`iot.amazonaws.com`) 呼叫 Lambda 函數的許可。
**--source-arn**
此欄位確認僅 AWS IoT 中的 `arn:aws:iot:region:1111-1111-1111:rule/example-rule` 會觸發此 Lambda 函數，且相同或不同帳戶中的任何其他規則皆無法啟動此 Lambda 函數。
**--source-account**
此欄位會確認 僅代表`1111-1111-1111`帳戶 AWS IoT 啟用此 Lambda 函數。
**備註**
若您看到來自 AWS Lambda 函數主控台 **Configuration** (組態) 之下的錯誤訊息「找不到規則」，請略過錯誤訊息並繼續測試連線。
# 錯誤處理 (錯誤動作)
當 AWS IoT 收到來自裝置的訊息時，規則引擎會檢查訊息是否符合規則。若是如此，則會對規則的查詢陳述式進行評估，並啟動規則的動作，傳送查詢陳述式的結果。
如果在啟動動作時發生問題，則若針對規則指定了錯誤動作，規則引擎便會啟動該動作。這可能在以下情況時發生：
+ 規則並未擁有存取 Amazon S3 儲存貯體的許可。
+ 使用者錯誤會造成 DynamoDB 佈建的傳輸量超量。
**注意**
本主題所述的錯誤處理適用於[規則動作](iot-rule-actions.md)。若要偵錯 SQL 問題，包括外部函數，您可以設定 AWS IoT 記錄。如需詳細資訊，請參閱[設定 AWS 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
觸發錯誤動作的規則名稱。
主題
收到原始訊息的主題。
cloudwatchTraceId
指向 CloudWatch 中錯誤記錄的專屬識別資料。
clientId
訊息發佈者的用戶端 ID。
base64OriginalPayload
原始訊息承載 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.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html)，包括外部函數：[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda)、[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb)、[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data)、[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow)[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret)、 [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning)和 [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64)。如果錯誤動作需要呼叫外部 函數，則叫用錯誤動作可能會導致外部函數產生額外的帳單。
如需規則以及如何指定錯誤動作的詳細資訊，請參閱[建立 AWS IoT 規則](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-rule.html)。
若需更多有關使用 CloudWatch 監控規則成功或失敗的資訊，請參閱 [AWS IoT 指標和維度](metrics_dimensions.md)。
# 使用基本擷取減少簡訊費用
您可以使用 Basic Ingest，安全地將裝置資料傳送至 AWS 服務 支援的 [AWS IoT 規則動作](iot-rule-actions.md)，而不會產生[傳訊成本 ](https://aws.amazon.com/iot-core/pricing/)。基本擷取會從擷取路徑移除發佈/訂閱訊息代理程式，讓資料流程最佳化。
基本擷取可從您的裝置或應用程式傳送訊息。訊息的前三個層級具有以 `$aws/rules/rule_name` 開頭的主題名稱，其中 `rule_name` 是您要叫用的 AWS IoT 規則的名稱。
您可將基本擷取字首 (`$aws/rules/rule_name`) 新增至您用來叫用規則的訊息主題，即可搭配基本擷取使用現有的規則。例如，如果您有一個名為 `BuildingManager` 規則會透過 `Buildings/Building5/Floor2/Room201/Lights` (`"sql": "SELECT * FROM 'Buildings/#'"`) 之類的訊息主題叫用，則您可以透過傳送主題為 `$aws/rules/BuildingManager/Buildings/Building5/Floor2/Room201/Lights` 的訊息，使用基本擷取叫用相同的規則。
**注意**
您的裝置和規則無法訂閱基本擷取預留主題。例如，指標 AWS IoT Device Defender `num-messages-received`不會發出，因為它不支援訂閱主題。如需詳細資訊，請參閱[預留主題](reserved-topics.md)。
如果您需要發佈/訂閱代理程式將訊息分發給多個訂閱者 （例如，將訊息傳遞至其他裝置和規則引擎），您應該繼續使用 AWS IoT 訊息代理程式來處理訊息分發。不過，請確認使用基本擷取主題以外的主題來發佈您的訊息。
## 使用基本擷取
在使用基本擷取之前，請驗證您的裝置或應用程式是否正在使用對 `$aws/rules/*` 具有發佈許可的[政策](iot-policies.md)。或者，您可以在 政策`$aws/rules/rule_name/*`中指定個別規則的許可。除此之外，您的裝置和應用程式可以繼續使用他們與 AWS IoT Core的現有連線。
當訊息抵達規則引擎時，從基本擷取叫用的規則和透過訊息代理程式訂閱叫用的規則，在實作或錯誤處理上就沒有差別。
您可以建立用於基本擷取的規則。請謹記以下幾點：
+ 基本擷取主題的初始字首 (`$aws/rules/rule_name`) 無法用於 [topic(Decimal)](iot-sql-functions.md#iot-function-topic) 函數。
+ 如果您定義了只能由基本擷取叫用的規則，`rule` 定義中 `sql` 欄位的 `FROM` 子句則為選用。如果規則也需要由必須透過訊息代理程式傳送的其他訊息呼叫 (例如，因為那些其他訊息必須分配到多個訂閱者)，則仍然會需要此項。如需詳細資訊，請參閱[AWS IoT SQL 參考](iot-sql-reference.md)。
+ 首三個層級的基本擷取主題 (`$aws/rules/rule_name`) 不會算在主題的 8 區段長度或 256 個總字元限制中。除此之外，適用其他相同限制，如 [AWS IoT 限制](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#limits_iot)所述。
+ 如果收到具有指定非作用中規則或不存在規則的基本擷取主題的訊息，則會在 Amazon 日誌中建立錯誤 CloudWatch 日誌，以協助您進行偵錯。如需詳細資訊，請參閱[Rules engine 日誌項目](cwl-format.md#rule-engine-logs)。系統會指出 `RuleNotFound` 指標，讓您可以為此指標建立警示。如需詳細資訊，請參閱 [規則指標](metrics_dimensions.md#rulemetrics) 中的規則指標。
+ 您仍可使用 QoS 1 發佈基本擷取主題。訊息成功交付至規則引擎PUBACK後，您會收到 。接收 PUBACK並不表示您的規則動作已成功完成。您可以設定錯誤動作，以在動作執行時處理錯誤。如需詳細資訊，請參閱[錯誤處理 (錯誤動作)](rule-error-handling.md)。
# AWS IoT SQL 參考
在 中 AWS 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)、[案例陳述式](iot-sql-case.md)、[JSON Extensions](iot-sql-json.md)、[變數](iot-sql-set.md#iot-sql-set-usage)和 [巢狀物件查詢](iot-sql-nested-queries.md)。
**SELECT**
(必要) 從傳入的訊息承載擷取資訊並對資訊執行轉換。要使用的訊息是由 FROM 子句中指定的[主題篩選條件](topics.md#topicfilters)所識別。
SELECT 子句支援 [資料類型](iot-sql-data-types.md)、[運算子](iot-sql-operators.md)、[函數](iot-sql-functions.md)、[文字](iot-sql-literals.md)、[案例陳述式](iot-sql-case.md)[JSON Extensions](iot-sql-json.md)、[替代範本](iot-substitution-templates.md)、、[變數](iot-sql-set.md#iot-sql-set-usage)、 [巢狀物件查詢](iot-sql-nested-queries.md)和 [二進位承載](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)[案例陳述式](iot-sql-case.md)、、[JSON Extensions](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"
}
```
該資料接下來會轉送給該規則的動作，並發送資料以進行更多處理作業。如需規則動作的詳細資訊，請參閱 [AWS IoT 規則動作](iot-rule-actions.md)。
**注意**
AWS IoT SQL 語法目前不支援註解。
包含空格的屬性名稱不能用作 SQL 陳述式中的欄位名稱。雖然傳入的承載可以包含含有空格的屬性名稱，但這些名稱不能在 SQL 陳述式中使用。但是，如果您使用萬用字元 (\$1) 欄位名稱規範，這些名稱會被傳遞到傳出承載。
# SELECT 子句
AWS IoT SELECT 子句基本上與 ANSI SQL SELECT 子句相同，但有一些細微差異。
SELECT 子句支援 [資料類型](iot-sql-data-types.md)、[運算子](iot-sql-operators.md)、[函數](iot-sql-functions.md)、[文字](iot-sql-literals.md)、[案例陳述式](iot-sql-case.md)[JSON Extensions](iot-sql-json.md)、、[變數](iot-sql-set.md#iot-sql-set-usage)、 [巢狀物件查詢](iot-sql-nested-queries.md)和 [二進位承載](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 Extensions](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}` (表示主題/子主題)、`{t: 60}` (表示主題/子主題 2) 和 `{t: 70}` (表示主題/子主題 3/詳細資訊) 的承載傳送給其動作。它沒有訂閱 `'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)、[案例陳述式](iot-sql-case.md)、[JSON Extensions](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 關鍵字
## 使用變數
定義變數之後，您可以在以下位置使用它們：
+ SELECT 子句
+ WHERE 子句
+ 其他 SET 變數指派
+ 動作替換範本
+ 錯誤動作替換範本
+ 巢狀 SELECT 查詢
+ 函數參數 （某些參數，例如 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 Extensions](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 子句限制
下列限制適用於 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)、[案例陳述式](iot-sql-case.md)、[JSON Extensions](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 承載：`80`
SQL:``SELECT decode(encode(*, 'base64'), 'base64') AS value FROM 'topic/subtopic' WHERE decode(encode(*, 'base64'), 'base64') > 50`
在此情況下，該規則會觸發，並且執行由規則指定的動作。傳出承載將由 SELECT 子句轉換為 JSON 承載 `{"value":80}`。
# 資料類型
AWS 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. AWS IoT attempts，以剖析符合規則表達式的字串：^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1。「0」、「-1.2」、「5E-12」均為自動轉換為 Decimal 的範例字串。 |
| Array | Undefined. |
| 物件 | Undefined. |
| Null | Null. |
| 未定義 | Undefined. |
**To Int**
| 引數類型 | 結果 |
| --- | --- |
| Int | 來源值。 |
| Decimal | 四捨五入到最接近 Int 的來源值。 |
| Boolean | Undefined。(您可以明確使用 Cast 函數轉換 true = 1.0、false = 0.0。) |
| String | SQL 引擎會嘗試將字串剖析為 Decimal. AWS IoT attempts，以剖析符合規則表達式的字串：^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1。"0"、"-1.2"、"5E-12" 是字串的所有範例，這些字串會自動轉換為 Decimals. AWS IoT attempts，以String將 轉換為 Decimal，然後截斷該字串的小數位Decimal數以製作 Int。 |
| Array | 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。 |
| Array | Undefined. |
| 物件 | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
**To String**
| 引數類型 | 結果 |
| --- | --- |
| Int | 以標準表示法表示的 Int 的字串顯示方式。 |
| Decimal | 代表 Decimal 值的字串，可能是採取科學表示法。 |
| Boolean | 「true」或「false」。所有小寫。 |
| String | 原始的值。 |
| 陣列 | 序列化為 JSON 的 Array。該結果字串為以逗號分隔的清單，並包含在方括弧內。String 在括號中。Decimal、Int、Boolean 和 Null 則不是。 |
| 物件 | 序列化為 JSON 的物件。該結果字串為以逗號分隔的鍵值組清單，並以大括號為開頭和結尾。String 在括號中。Decimal、Int、Boolean 和 Null 則不是。 |
| Null | Undefined. |
| 未定義 | 未定義。 |
# 運算子
下列運算子可用於 SELECT 和 WHERE 子句。
## AND 運算子
傳回 `Boolean` 結果。執行邏輯 AND 運算。如果左右運算元為 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` 結果。執行邏輯 OR 運算。如果右運算元或左運算元有一個為 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` 結果。執行邏輯 NOT 運算。如果運算元為 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，因為 3 存在於名為 的陣列中`arr`。因此，在 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，因為 3 存在於名為 的陣列中`arr`。因此，在 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. |
## >= 運算子
傳回 `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` 結果。如果左側運算元少於右運算元。兩個運算元均轉換為 `Decimal`，再做比較。
*語法：*`expression < expression`。
**< 運算子**
| 左運算元 | 右運算元 | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean。如果左運算元小於右運算元即為 true。否則為 false。 |
| String/Int/Decimal | String/Int/Decimal | 如果所有字串均可轉換為 Decimal，即 Boolean。如果左側運算元少於右運算元。否則為 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。鍵/值的順序不重要。 |
| Null | Null | False。 |
| 任何值 | 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。鍵/值的順序不重要。 |
| 任何值 | 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.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda)、[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data)、 [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb)和 [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow)。只有在您將 [Protobuf 訊息解碼至 JSON](https://docs.aws.amazon.com//iot/latest/developerguide/binary-payloads.html#binary-payloads-protobuf) 時，您才會收到[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64)函數的帳單。如需詳細資訊，請參閱 [AWS IoT Core 定價頁面](https://aws.amazon.com/iot-core/pricing/)。
## abs(Decimal)
傳回某個數字的絕對值。受 SQL 版本 2015-10-08 和更新版本支援。
範例：`abs(-5)` 傳回 5。
****
| 引數類型 | 結果 |
| --- | --- |
| Int | Int，引數的絕對值。 |
| Decimal | Decimal，引數的絕對值。 |
| Boolean | Undefined. |
| String | Decimal。結果為引數的絕對值。如果字串無法轉換，則結果為 Undefined。 |
| Array | Undefined. |
| 物件 | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
## accountid()
將擁有此規則的帳戶 ID 傳回為 `String`。受 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。 |
| Array | 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。 |
| Array | 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。 |
| Array | 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。
**引數**
| 引數 | Description |
| --- | --- |
| functionArn | Lambda 函數呼叫的 ARN。Lambda 函數必須傳回 JSON 資料。 |
| inputJson | 傳遞到 Lambda 函數的 JSON 輸入。若要傳遞巢狀物件查詢和文字，您必須使用 SQL 版本 2016-03-23。 |
您必須授予 AWS IoT `lambda:InvokeFunction`叫用指定 Lambda 函數的許可。下列範例顯示了如何使用 AWS 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
您帳戶的 AWS 區域 。
--principal
取得許可的委託人。這應該`iot.amazonaws.com`允許呼叫 Lambda 函數的 AWS IoT 許可。
--source-arn
該項規則的 ARN。您可以使用 **get-topic-rule** AWS CLI 命令來取得規則的 ARN。
--source-account
定義規則 AWS 帳戶 的 。
--statement-id
專屬的陳述式識別符。
--action
您想要在此陳述式中允許的 Lambda 動作。若要允許 AWS IoT 叫用 Lambda 函數，請指定 `lambda:InvokeFunction`。
**重要**
如果您在未提供 `source-arn`或 的情況下新增 AWS IoT 委託人的許可`source-account`，任何 AWS 帳戶 使用 Lambda 動作建立規則的 都可以觸發規則來叫用您的 Lambda 函數 AWS IoT。如需詳細資訊，請參閱 [Lambda 許可模型](https://docs.aws.amazon.com/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` 會從發佈在「主題/子主題」主題上的訊息選取資料。
`some.value` 會從 Lambda 函數產生的輸出結果中選取資料。
**注意**
該規則引擎會限制 Lambda 函數的執行期間。規則的 Lambda 函數呼叫應該會在 2000 毫秒內完成。
## bitand (Int、Int)
在兩個 `Int` (已轉換) 引數的位元表現上執行按位元的 AND 運算。受 SQL 版本 2015-10-08 和更新版本支援。
範例：`bitand(13, 5)` = 5
****
| 引數類型 | 引數類型 | 結果 |
| --- | --- | --- |
| Int | Int | Int，兩個引數按位元的 AND 運算。 |
| Int/Decimal | Int/Decimal | Int，兩個引數按位元的 AND 運算。所有非 Int 的數字會無條件捨去至最接近的 Int。如果任何引數無法轉換至 Int，結果會為 Undefined。 |
| Int/Decimal/String | Int/Decimal/String | Int，兩個引數按位元的 AND 運算。所有字串都會轉換為小數，並會無條件捨去至最接近的 Int (整數)。如果轉換失敗，則結果為 Undefined。 |
| 其他值 | 其他值 | Undefined. |
## bitor(Int, Int)
在兩個引數的位元表現上執行按位元的 OR 運算。受 SQL 版本 2015-10-08 和更新版本支援。
範例：`bitor(8, 5)` = 13
****
| 引數類型 | 引數類型 | 結果 |
| --- | --- | --- |
| Int | Int | Int，兩個引數按位元的 OR 運算。 |
| Int/Decimal | Int/Decimal | Int，兩個引數按位元的 OR 運算。所有非 Int 的數字會無條件捨去至最接近的 Int。如果轉換失敗，則結果為 Undefined。 |
| Int/Decimal/String | Int/Decimal/String | Int，兩個引數按位元的 OR 運算。所有字串都會轉換為小數，並會無條件捨去至最接近的 Int (整數)。如果轉換失敗，則結果為 Undefined。 |
| 其他值 | 其他值 | Undefined. |
## bitxor(Int, Int)
在兩個 `Int` (已轉換) 引數的位元表現上執行按位元的 XOR 運算。受 SQL 版本 2015-10-08 和更新版本支援。
範例：`bitor(13, 5)` = 8
****
| 引數類型 | 引數類型 | 結果 |
| --- | --- | --- |
| Int | Int | Int，兩個引數按位元的 XOR 運算。 |
| Int/Decimal | Int/Decimal | Int，兩個引數按位元的 XOR 運算。非 Int 的數字會無條件捨去至最接近的 Int。 |
| Int/Decimal/String | Int/Decimal/String | Int 是在兩個引數上的位元 XOR。字串會轉換為小數，並無條件捨去至最接近的 Int。如果任何轉換失敗，則結果為 Undefined。 |
| 其他值 | 其他值 | Undefined. |
## bitnot(Int)
在 `Int` (已轉換) 引數的位元表現上執行按位元的 NOT 運算。受 SQL 版本 2015-10-08 和更新版本支援。
範例：`bitnot(13)` = 2
****
| 引數類型 | 結果 |
| --- | --- |
| Int | Int，引數按位元的 NOT 運算。 |
| Decimal | Int，引數按位元的 NOT 運算。Decimal值會無條件捨去至最接近 Int 的值。 |
| String | Int，引數按位元的 NOT 運算。字串會轉換為小數，並會無條件捨去至最接近的 Int (整數)。如果任何轉換失敗，則結果為 Undefined。 |
| 其他值 | 其他值。 |
## cast()
將一個值從某個資料類型轉換至另一個類型。除了增加了將數字和布林值相互轉換的能力外，轉換行為大致如同標準轉換。如果 AWS IoT 無法判斷如何將一種類型轉換為另一種類型，則結果為 `Undefined`。受 SQL 版本 2015-10-08 和更新版本支援。格式：cast (*value* as *type*)。
範例：
`cast(true as Int) ` = 1
在呼叫 `cast` 時，以下關鍵字可能出現在「as」之後：
**對於 SQL 版本 2015-10-08 與 2016-03-23**
| 關鍵字 | 結果 |
| --- | --- |
| String | 將值轉換為 String。 |
| Nvarchar | 將值轉換為 String。 |
| 文字 | 將值轉換為 String。 |
| Ntext | 將值轉換為 String。 |
| varchar | 將值轉換為 String。 |
| Int | 將值轉換為 Int。 |
| Integer | 將值轉換為 Int。 |
| Double | 將值轉換為 Decimal (使用雙精度)。 |
**此外，對於 SQL 版本 2016-03-23**
| 關鍵字 | 結果 |
| --- | --- |
| Decimal | 將值轉換為 Decimal。 |
| Bool | 將值轉換為 Boolean。 |
| Boolean | 將值轉換為 Boolean。 |
轉換規則：
**轉換為小數**
| 引數類型 | 結果 |
| --- | --- |
| 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。 AWS IoT 會嘗試剖析字串以符合正規表示式：^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1。「0」、「-1.2」、「5E-12」均為自動轉換為 Decimal 的範例字串。 |
| Array | Undefined. |
| 物件 | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
**轉換為 Int**
| 引數類型 | 結果 |
| --- | --- |
| Int | 來源值。 |
| Decimal | 無條件捨去至最接近 Int 的來源值。 |
| Boolean | true = 1.0、false = 0.0。 |
| String | 嘗試將字串剖析為 Decimal。 AWS IoT 會嘗試剖析字串以符合正規表示式：^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1。「0」、「-1.2」、「5E-12」均為自動轉換為 Decimal 的範例字串。 AWS IoT 會嘗試將字串轉換為 Decimal，並無條件捨去至最接近的 Int。 |
| Array | Undefined. |
| 物件 | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
**轉換到 `Boolean`**
| 引數類型 | 結果 |
| --- | --- |
| Int | 0 = False，any\$1nonzero\$1value = True。 |
| Decimal | 0 = False，any\$1nonzero\$1value = True。 |
| Boolean | 來源值。 |
| String | 「true」= True 而「false」= False (不區分大小寫)。其他字串值 = Undefined。 |
| Array | Undefined. |
| 物件 | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
**轉換為字串**
| 引數類型 | 結果 |
| --- | --- |
| 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。 |
| Array | 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。 |
| Array | 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。 |
| Array | Undefined. |
| 物件 | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
## decode(value, decodingScheme)
使用 `decode` 函數來解碼已編碼值。如果解碼字串為 JSON 文件，則會傳回可定址物件。否則，解碼字串會當成字串傳回。如果字串無法解碼，函數會傳回 NULL。此功能支援解碼 base64 編碼字串及協定緩衝區 (protobuf) 訊息格式。
受 SQL 版本 2016-03-23 和更新版本支援。
value
字串值或任何有效的表達式 (如 [AWS 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)。
**重要**
如果您在設定 AWS IoT 委託人的許可`source‐account`時省略 `source‐arn`或 ，任何 AWS 帳戶 都可以透過其他 AWS IoT 規則叫用您的解碼函數。若要保護您的函數，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[儲存貯體政策](https://docs.aws.amazon.com/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`
存放在名為 `s3-bucket` 的 Amazon S3 儲存貯體中的 `FileDescriptorSet` 檔案。
+ `myproto`
此原始 `.proto` 檔案的用途是產生名為 `myproto.proto` 的 `FileDescriptorSet` 檔案。
+ `messagetype`
如 `myproto.proto` 中所定義名為 `messagetype` 的訊息類型(以及任何匯入的相依性)。
## encode(value, encodingScheme)
根據編碼機制，使用 `encode` 函數將承載 (可能並非 JSON 資料) 編碼為字串表現形式。受 SQL 版本 2016-03-23 和更新版本支援。
value
任何有效的表達式，如 [AWS IoT SQL 參考](iot-sql-reference.md) 的定義。無論承載是否為 JSON 格式，您都可以指定 \$1 以編碼整個承載。若您提供了運算式，則在編碼之前，評估結果將轉換為字串。
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. |
## get
從集合類型 (陣列、字串、物件) 擷取值。第一個引數不會套用任何轉換。轉換會按表格中的記錄套用至第二個引數。受 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的邊界之外 (負值或 >= array.length)，則結果為 Undefined。 |
| String | 任何類型 (轉換為 Int) | 第二個引數 (轉換為 Int) 所提供的字串從零開始的索引的字元。如果轉換不成功，則結果為 Undefined。如果索引在字串的邊界之外 (負值或 >= string.length)，則結果為 Undefined。 |
| 物件 | String (未套用轉換) | 對應至第二個引數所提供的字串鍵的第一個引數物件所儲存的值。 |
| 其他值 | 任何值 | Undefined. |
## get\$1dynamodb(tableName, partitionKeyName, partitionKeyValue, sortKeyName, sortKeyValue, roleArn)
從 DynamoDB 資料表擷取資料。`get_dynamodb()` 允許您在評估規則時查詢 DynamoDB 資料表。您可以使用從 DynamoDB 中擷取的資料來篩選或增強訊息承載。受 SQL 版本 2016-03-23 和更新版本支援。
`get_dynamodb()` 接受下列參數：
tableName
所要查詢 DynamoDB 資料表的名稱。
partitionKeyName
分割區索引鍵的名稱。如需詳細資訊，請參閱 [DynamoDB 索引鍵](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey)。
partitionKeyValue
用來識別記錄的分割區索引鍵值。如需詳細資訊，請參閱 [DynamoDB 索引鍵](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey)。
sortKeyName
(選用) 排序索引鍵的名稱。只有在查詢的 DynamoDB 資料表使用複合索引鍵時，才需要此參數。如需詳細資訊，請參閱 [DynamoDB 索引鍵](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey)。
sortKeyValue
(選用) 排序索引鍵的值。只有在查詢的 DynamoDB 資料表使用複合索引鍵時，才需要此參數。如需詳細資訊，請參閱 [DynamoDB 索引鍵](https://docs.aws.amazon.com/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 資料表，其中包含所有連接至 AWS 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(名稱)
參考下列任一 MQTT5 標頭：`contentType`、`payLoadFormatIndicator`、`responseTopic`、和 `correlationData`。此函數會接受下列任何常值字串做為引數：`content_type`、`format_indicator`、`response_topic` 和 `correlation_data`。如需詳細資訊，請參閱下列**函數引數**表。
ContentType
字串：描述發佈訊息內容的 UTF-8 編碼字串。
payLoadFormatIndicator
字串：列舉字串值，用於表示承載是否已格式化為 UTF-8。有效值為 `UNSPECIFIED_BYTES` 和 `UTF8_DATA`。
responseTopic
字串：UTF-8 編碼字串，用來當作回應訊息的主題名稱。回應主題是用來描述要在請求-回應流程中作為接收者發佈目標的主題。主題不得包含萬用字元。
correlationData
字串：請求訊息的傳送者使用 base64 編碼的二進位資料，用以在收到回應訊息時識別其所對應的請求。
下表列出可接受的函數引數及其相關聯的 `get_mqtt_property` 函數傳回類型：
**函數引數**
| SQL | 傳回資料類型 (如果存在) | 傳回資料類型 (如果不存在) |
| --- | --- | --- |
| get\$1mqtt\$1property("format\$1indicator") | 字串 (UNSPECIFIED\$1BYTES 或 UTF8\$1DATA) | 字串 (NSPECIFIED\$1BYTES) |
| get\$1mqtt\$1property("content\$1type") | String | 未定義 |
| get\$1mqtt\$1property("response\$1topic") | String | 未定義 |
| get\$1mqtt\$1property("correlation\$1data") | base64 編碼字串 | 未定義 |
| get\$1mqtt\$1property("some\$1invalid\$1name") | 未定義 | 未定義 |
下列範例規則 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(expression， defaultValue)
如果指定，則傳回第二個參數中的預設值，否則當第一個參數中的運算式傳回 null、未定義或失敗時，傳回未定義的預設值。受 SQL 版本 2016-03-23 和更新版本支援。
**重要**
`get_or_default` 不如預期直接支援非 JSON 承載。如果您使用的是非 JSON 承載，請使用 `encode`或 `decode`函數。
`get_or_default()` 接受下列參數：
表達式
任何包含 [資料類型](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 Extensions](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 Extensions](iot-sql-json.md)。這是當第一個引數傳回 null、未定義或失敗時要傳回的值。
defaultValue 參數不允許從客戶擁有的資源擷取資料的函數，例如 get\$1secret、get\$1dynamodb、aws\$1lambda、get\$1thing\$1shadow、decode-protobuf 和 machinelearning\$1predict。
下表顯示每個引數及其相關聯輸出可接受的函數引數：
| 第一個引數 | 第二個引數 | Output |
| --- | --- | --- |
| 成功的評估 | 任何值或未指定 | 第一個引數值。 |
| 未定義、Null 或失敗 | 任何值，包括未定義或 Null | 第二個引數值。 |
| 未定義、Null 或失敗 | 未指定 | Undefined |
**範例**：
範例 1：
如果 DynamoDB 資料表或查詢失敗，下列範例會提供 defaultValue 值：
```
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 陳述式將評估為 `{}`，並嘗試任何規則動作。
**重要**
建議您遵循這些最佳實務，以維護使用此函數時的安全性：
避免在規則定義中使用硬式編碼秘密，包括預設值
使用 AWS Secrets Manager 管理敏感資訊
## get\$1registry\$1data(registryAPI， thingName， roleArn)
擷取 AWS IoT 規則中的 AWS IoT 物件登錄檔資料。您可以讀取登錄檔資料 （例如屬性、物件類型和裝置所屬的物件群組），並使用此資訊來篩選、豐富或動態路由訊息。受 SQL 版本 2016-03-23 和更新版本支援。
`get_registry_data()` 接受下列參數：
registryAPI
正在呼叫的登錄 API。有效值為 `DescribeThing` 和 `ListThingGroupsForThing`。這些值必須是常數字串。
thingName
字串：您要擷取其登錄檔資料之物件的名稱。
roleArn
字串：根據所呼叫 API 具有`iot:DescribeThing`許可和/或`iot:ListThingGroupsForThing`許可的角色 ARN。
`get_registry_data` 函數的回應格式與呼叫的登錄 API 相同。如需詳細資訊，請參閱 [DescribeThing](https://docs.aws.amazon.com//iot/latest/apireference/API_DescribeThing.html) 和 [ListThingGroupsForThing](https://docs.aws.amazon.com//iot/latest/apireference/API_ListThingGroupsForThing.html) APIs。
範例：
您可以擷取物件類型資訊，以允許篩選物件類型為 之物件 （物件名稱符合 MQTT 用戶端 ID) 的 AWS 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)
擷取所加密 `SecretString` 或 `SecretBinary` 欄位的值，此欄位是 [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) 中目前秘密版本的欄位。如需建立和維護秘密的詳細資訊，請參閱 [CreateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html)、[UpdateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_UpdateSecret.html) 和 [PutSecretValue](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_PutSecretValue.html)。
`get_secret()` 接受下列參數：
secretId
字串：要擷取之秘密的 Amazon 資源名稱 (ARN) 或易記名稱。
secretType
字串：秘密類型。有效值：`SecretString` \$1 `SecretBinary`。
SecretString
+ 對於您使用 APIs AWS CLI、 或 AWS Secrets Manager 主控台建立為 JSON 物件的秘密：
+ 如果您指定 `key` 參數的值，此函數會傳回所指定金鑰的值。
+ 如果未指定 `key` 參數的值，此函數會傳回整個 JSON 物件。
+ 對於您使用 API 或 AWS CLI建立為非 JSON 物件的秘密：
+ 如果您指定 `key` 參數的值，此函數會失敗並顯示例外狀況。
+ 如果未指定 `key` 參數的值，此函數會傳回秘密的內容。
SecretBinary
+ 如果您指定 `key` 參數的值，此函數會失敗並顯示例外狀況。
+ 如果未指定 `key` 參數的值，此函數會以 Base64 編碼的 UTF-8 字串形式傳回秘密值。
key
(選用) 字串：JSON 物件內的金鑰名稱，此物件存放在秘密的 `SecretString` 欄位中。當您只想要擷取存放在秘密中的秘密值，而不是整個 JSON 物件時，請使用此值。
如果您指定此參數的值，而且秘密並未在其 `SecretString` 欄位內包含 JSON 物件，此函數會失敗並顯示例外狀況。
roleArn
字串：擁有 `secretsmanager:GetSecretValue` 和 `secretsmanager:DescribeSecret` 許可的角色 ARN。
**注意**
此函數一律傳回目前版本的秘密 (標籤為 `AWSCURRENT` 的版本)。 AWS IoT 規則引擎會快取每個秘密最多 15 分鐘。因此，規則引擎最多可能需要 15 分鐘來更新秘密。這表示如果您在使用 更新後最多 15 分鐘內擷取秘密 AWS Secrets Manager，此函數可能會傳回先前的版本。
此函數不會計量，但會 AWS Secrets Manager 收取費用。由於秘密快取機制，規則引擎偶爾會呼叫 AWS 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
字串：想要擷取影子的物件名稱。
shadowName
(選用) 字串：影子的名稱。只有在參考已命名的影子時，才需要此參數。
roleArn
字串：擁有 `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 value', 'value with duplicate key'] |
| get\$1user\$1properties(「其他索引鍵」) | 字串陣列 | ['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(「不存在的索引鍵」) | 未定義 | |
下列範例規則 SQL 會將使用者屬性 (MQTT5 屬性標頭類型) 參考到承載中：
```
SELECT *, get_user_properties('user defined property key') as userProperty
FROM 'some/topic'
```
## 雜湊函數
AWS IoT 提供下列雜湊函數：
+ md2
+ md5
+ sha1
+ sha224
+ sha256
+ sha384
+ sha512
所有雜湊函數都預期有一個字串引數。結果為該字串的雜湊值。標準字串轉換會套用至非字串的引數。SQL 版本 2015-10-08 和更新版本可支援所有雜湊函數。
範例：
`md2("hello")` = "a9046c73e00331af68917d3804f70655"
`md5("hello")` = "5d41402abc4b2a76b9719d911017c592"
## indexof(String, String)
傳回第二個引數的第一個索引 (從 0 開始)，作為第一個引數的子字串。預期兩個引數均為字串。非字串的引數需遵守標準字串轉換規則。此函數不能套用在陣列上，僅可套用到字串上。受 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。 |
| Array | 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。 |
| Array | 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，然後 LPAD 函數會套用至該 String。如果其無法轉換，則結果為 Undefined。 |
| 任何值 | 其他值 | Undefined. |
## ltrim(String)
移除所給的 `String` 前方所有空格 (tab 與空格)。受 SQL 版本 2015-10-08 和更新版本支援。
範例：
`Ltrim(" h i ")` = "hi "。
****
| 引數類型 | 結果 |
| --- | --- |
| Int | 移除 Int 前方所有空格的 String 顯示方式。 |
| Decimal | 移除 Decimal 前方所有空格的 String 顯示方式。 |
| Boolean | 移除布林值 (「true」或「false」) 前方所有空格的 String 顯示方式。 |
| String | 移除前方所有空格的引數。 |
| 陣列 | String (使用標準轉換規則) 的 Array 顯示方式，且移除所有前置空格。 |
| 物件 | Object (使用標準轉換規則) 的 String 顯示方式，且移除所有前置空格。 |
| Null | Undefined. |
| 未定義 | Undefined. |
## machinelearning\$1predict(modelId, roleArn, record)
使用 `machinelearning_predict`函數，根據 Amazon SageMaker AI 模型使用來自 MQTT 訊息的資料進行預測。受 SQL 版本 2015-10-08 和更新版本支援。`machinelearning_predict` 函數的引數如下：
modelId
要對其執行預測的模型 ID。必須啟用該模型的即時端點。
roleArn
IAM 角色具有擁有 `machinelearning:Predict` 和 `machinelearning:GetMLModel` 許可的政策，且允許存取要對其執行預測的模型。
record
要傳遞至 SageMaker AI 預測 API 的資料。此應顯示為單層 JSON 物件。若該記錄為多層級 JSON 物件，則記錄會透過值的序列化來扁平化。例如，以下 JSON：
```
{ "key1": {"innerKey1": "value1"}, "key2": 0}
```
會變成：
```
{ "key1": "{\"innerKey1\": \"value1\"}", "key2": 0}
```
該函數會傳回具有以下欄位的 JSON 物件：
predictedLabel
根據模型的輸入分類。
詳細資訊
包含下列屬性：
PredictiveModelType
模型類型。有效值為 REGRESSION、BINARY、MULTICLASS。
演算法
SageMaker AI 用來進行預測的演算法。該值必須為 SGD。
predictedScores
包含對應至每個標籤的原始分類分數。
predictedValue
SageMaker AI 預測的值。
## mod(Decimal, Decimal)
傳回第一個引數除以第二的引數的餘數。等同於 [remainder(Decimal, Decimal)](#iot-func-remainder)。也可以使用「%」當做同樣的模除功能的 infix 運算子。受 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` 函數來設定時間戳記格式，變成人類易懂的日期/時間格式。受 SQL 版本 2016-03-23 和更新版本支援。若要將時間戳記字串轉換為毫秒，請參閱 [time\$1to\$1epoch(String, String)](#iot-sql-function-time-to-epoch)。
`parse_time` 函數預期下列引數：
pattern
(字串) 遵循 [Joda-Time 格式](http://www.joda.org/joda-time/apidocs/org/joda/time/format/DateTimeFormat.html)的日期/時間模式。
timestamp
(Long) 自 Unix epoch 起以毫秒單位設定格式的時間。請參閱函數 [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 憑證指紋 |
| AWS IoT 主控台 MQTT 用戶端 | MQTT | IAM 使用者或角色 | iam-role-id:session-name |
| AWS CLI | HTTP | IAM 使用者或角色 | userid |
| AWS IoT 裝置 SDK | MQTT | X.509 裝置憑證 | X.509 憑證指紋 |
| AWS IoT 裝置 SDK | MQTT over 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 | Int 的 String 顯示方式。 |
| Decimal | Decimal 的 String 顯示方式。 |
| Boolean | 布林值 (「true」或「false」) 的 String 顯示方式。 |
| String | String。 |
| 陣列 | Array (使用標準轉換規則) 的 String 顯示方式。 |
| 物件 | Object (使用標準轉換規則) 的 String 顯示方式。 |
| Null | Undefined. |
| 未定義 | Undefined. |
*第二個引數：*
必須為有效的 regex 表達式。非字串類型都會使用標準轉換規則轉換為 `String`。根據類型，結果字串可能不是有效的正規運算式。如果 (轉換的) 引數並非有效的 regex 值，結果會為 `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 | Int 的 String 顯示方式。 |
| Decimal | Decimal 的 String 顯示方式。 |
| Boolean | 布林值 (「true」或「false」) 的 String 顯示方式。 |
| String | 來源值。 |
| 陣列 | Array (使用標準轉換規則) 的 String 顯示方式。 |
| 物件 | Object (使用標準轉換規則) 的 String 顯示方式。 |
| Null | Undefined. |
| 未定義 | Undefined. |
*第二個引數：*
必須為有效的 regex 表達式。非字串類型都會使用標準轉換規則轉換為 `String`。根據類型，結果字串可能不是有效的正規運算式。如果 (轉換的) 引數並非有效的 regex 表達式，則結果為 `Undefined`。
*第三個引數：*
必須為有效的 regex 替換字串。(可以參考擷取群組)。非字串類型都會使用標準轉換規則轉換為 `String`。如果 (轉換的) 引數並非有效的 regex 替換字串，則結果為 `Undefined`。
## regexp\$1substr(String, String)
在第一個參數中尋找第一個符合第二個參數 (regex) 的值。請以「\$1」參考擷取群組。受 SQL 版本 2015-10-08 和更新版本支援。
範例：
`regexp_substr("hihihello", "hi")` = "hi"
`regexp_substr("hihihello", "(hi)*")` = "hihi"
**第一個引數：**
| 引數類型 | 結果 |
| --- | --- |
| Int | Int 的 String 顯示方式。 |
| Decimal | Decimal 的 String 顯示方式。 |
| Boolean | 布林值 (「true」或「false」) 的 String 顯示方式。 |
| String | String 引數。 |
| 陣列 | Array (使用標準轉換規則) 的 String 顯示方式。 |
| 物件 | Object (使用標準轉換規則) 的 String 顯示方式。 |
| Null | Undefined. |
| 未定義 | Undefined. |
*第二個引數：*
必須為有效的 regex 表達式。非字串類型都會使用標準轉換規則轉換為 `String`。根據類型，結果字串可能不是有效的正規運算式。如果 (轉換的) 引數並非有效的 regex 表達式，則結果為 `Undefined`。
## remainder(Decimal, Decimal)
傳回第一個引數除以第二的引數的餘數。等同於 [mod(Decimal, Decimal)](#iot-func-mod)。也可以使用「%」當做同樣的模除功能的 infix 運算子。受 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 | Int 的 String 顯示方式。 |
| Decimal | Decimal 的 String 顯示方式。 |
| Boolean | 布林值 (「true」或「false」) 的 String 顯示方式。 |
| String | 來源值。 |
| 陣列 | Array (使用標準轉換規則) 的 String 顯示方式。 |
| 物件 | Object (使用標準轉換規則) 的 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，而 rpad 函數將套用到該 String 上。如果其無法轉換，則結果為 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` 後方所有空格 (tab 與空格)。受 SQL 版本 2015-10-08 和更新版本支援。
範例：
`rtrim(" h i ")` = " h i"
****
| 引數類型 | 結果 |
| --- | --- |
| Int | Int 的 String 顯示方式。 |
| Decimal | Decimal 的 String 顯示方式。 |
| Boolean | 布林值 (「true」或「false」) 的 String 顯示方式。 |
| 陣列 | Array (使用標準轉換規則) 的 String 顯示方式。 |
| 物件 | Object (使用標準轉換規則) 的 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。 |
| Array | 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。 |
| Array | 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'`
如何在 AWS IoT Core 規則動作中使用 sourceip() 函數的範例：
**範例 1**
下列範例顯示如何在 [DynamoDB 動作](https://docs.aws.amazon.com//iot/latest/developerguide/dynamodb-rule-action.html)中呼叫 () 函數作為[替換範本](https://docs.aws.amazon.com//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.aws.amazon.com//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.aws.amazon.com//iot/latest/developerguide/iot-basic-ingest.html)路徑傳遞至 AWS IoT Core 規則的訊息中擷取來源 IP 地址。您也可以擷取 IPv4 和 IPv6 訊息的來源 IP。來源 IP 顯示如下：
IPv6：`yyyy:yyyy:yyyy::yyyy:yyyy`
IPv4：`xxx.xxx.xxx.xxx`
**注意**
原始來源 IP 不會透過[重新發布動作](republish-rule-action.md)傳遞。
## substring(String, Int[, Int])
預期 `String` 後有一或兩個 `Int` 值。若為 `String` 和單個 `Int` 引數，此函數會從所給的 `String` 索引 (從 0 開始，包含 0) 到 `Int` 的結尾傳回所給的 `String` 的子字串。若為 `String` 和兩個 `Int` 引數，該函數會傳回從第一個 `String` 索引引數 (從 0 開始，包含 0) 到第二個 `Int` 索引引數 (從 0 開始，不含 0) 所提供的所給 `Int` 的子字串。少於零的索引將設為零。比 `String` 長度還長的索引會設為 `String` 長度。至於第三個引數版本，如果第一個索引大於 (或等於) 第二個索引，則結果為空的 `String`。
如果提供的引數不是 (*字串*、*整數*) 或 (*字串*、*整數*、*整數)*，則標準轉換會套用至該引數，以嘗試將那些引數轉換為正確類型。如果類型無法轉換，函數的結果即為 `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。 |
| Array | 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。 |
| Array | 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。 |
| Array | Undefined. |
| 物件 | Undefined. |
| Null | Undefined. |
| 未定義 | Undefined. |
## time\$1to\$1epoch(String, String)
使用 `time_to_epoch` 函數將時間戳字串轉換為 Unix epoch 時間中的毫秒數。受 SQL 版本 2016-03-23 和更新版本支援。若要將毫秒轉換為格式化的時間戳記字串，請參閱 [parse\$1time(String, Long[, String])](#iot-sql-function-parse-time)。
`time_to_epoch` 函數預期下列引數：
timestamp
(字串) 自 Unix epoch 起要轉換為毫秒的時間戳記字串。如果時間戳記字串未指定時區，函數會使用 UTC 時區。
pattern
(字串) 遵循 [JDK11 時間格式](http://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html)的日期/時間模式。
範例：
`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 日星期四 00：00：00 國際標準時間 (UTC) 開始的目前時間戳記，如 AWS IoT 規則引擎所觀察。受 SQL 版本 2015-10-08 和更新版本支援。
範例：`timestamp()` = `1481825251155`
## topic(Decimal)
傳回觸發該規則的訊息要傳送至的主題。如果未指定參數，則傳回整個主題。`Decimal` 參數用於指定特定主題區段，並會使用 1 指定第一個區段。對於 topic `foo/bar/baz`，topic(1) 會傳回 `foo`，topic(2) 會傳回 `bar`，依此類推。受 SQL 版本 2015-10-08 和更新版本支援。
範例：
`topic()` = "things/myThings/thingOne"
`topic(1)` = "things"
使用[基本擷取](iot-basic-ingest.md)時，topic() 函數無法使用主題的初始字首 (`$aws/rules/rule-name`)。例如，假定主題為：
`$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)
傳回物件的陣列，其中包含 `Array` 參數上 `Object` 參數的所指定轉換結果。
受 SQL 版本 2016-03-23 和更新版本支援。
String
要使用的轉換模式。請參閱下表以取得支援的轉換模式，以及了解它們如何從 `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 陳述式會使用 **transform()** 函數與 `enrichArray` 的 `String` 值搭配。在此範例中，`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 陳述式會使用 **transform()** 函數與 `enrichArray` 的 `String` 值搭配。**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。 |
| 陣列 | Array (使用標準轉換規則) 的 String 顯示方式。 |
| 物件 | Object (使用標準轉換規則) 的 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 子句中指定文字物件，很適合用於傳遞資訊。
**注意**
只有在使用 2016-03-23 版本或更高版本的 SQL 時才能使用文字。
會使用 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 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`，則案例陳述式的結果為 `Undefined`。
# JSON Extensions
您可以使用下列 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"
}
```
# 替代範本
您可以使用替代範本來擴增觸發規則時傳回的 JSON 資料，並 AWS IoT 執行動作。替代範本的語法是`${`*表達式*`}`，其中*表達式*可以是 SELECT 子句、WHERE 子句和 AWS IoT 中 支援的任何表達式[AWS IoT 規則動作](iot-rule-actions.md)。您可以將此表達式插入規則的動作欄位中，以便動態設定動作。實際上，此功能會取代動作中的資訊片段。這包含了在原始訊息中呈現的函數、運算子和資訊。
**重要**
因為替換範本中的運算式與「SELECT ...」陳述式是分開計算的，所以不能參考使用 AS 子句建立的別名。您只能參考原始承載、[函數](iot-sql-functions.md)和[運算子](iot-sql-operators.md)中呈現的資訊。
如需支援的表達式的詳細資訊，請參閱 [AWS IoT SQL 參考](iot-sql-reference.md)。
下列規則動作支援替代範本。每個動作都支援可以取代的不同欄位。
+ [Apache Kafka](apache-kafka-rule-action.md)
+ [CloudWatch 警示](cloudwatch-alarms-rule-action.md)
+ [CloudWatch Logs](cloudwatch-logs-rule-action.md)
+ [CloudWatch 指標](cloudwatch-metrics-rule-action.md)
+ [DynamoDB](dynamodb-rule-action.md)
+ [DynamoDBv2](dynamodb-v2-rule-action.md)
+ [Elasticsearch](elasticsearch-rule-action.md)
+ [HTTP](https-rule-action.md)
+ [AWS IoT Events](iotevents-rule-action.md)
+ [AWS IoT SiteWise](iotsitewise-rule-action.md)
+ [Kinesis Data Streams](kinesis-rule-action.md)
+ [Firehose](kinesis-firehose-rule-action.md)
+ [Lambda](lambda-rule-action.md)
+ [Location](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)
+ [步驟函數](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`，以 AWS 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` 子句的範例。
+ 對於二進位承載，您可以使用下方僅具有一個 \$1 的 `SELECT` 子句。
+
```
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.aws.amazon.com/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 可讓您以小封包大小並以比其他簡訊格式更快的速度傳送資料。 AWS IoT Core Rules 支援 protobuf，方法是提供 [decode(value， decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) SQL 函數，這可讓您將 protobuf 編碼的訊息承載解碼為 JSON 格式，並將其路由至下游服務。本節詳細介紹在 AWS IoT Core 規則中設定 protobuf 解碼的逐步流程。
**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`， AWS 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 儲存貯體
建立描述項檔案 之後`.desc`，請使用 AWS API、 AWS SDK 或 將描述項檔案上傳至 Amazon S3 `.desc`儲存貯體 AWS 管理主控台。
**重要考量**
+ 請確定您上傳描述項檔案到 中 Amazon S3 儲存貯 AWS 帳戶 體的 ，與您打算設定規則 AWS 區域 的位置相同。
+ 請務必授予`FileDescriptorSet`從 S3 讀取 的 AWS 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 儲存貯體使用 AWS Key Management Service 金鑰 (SSE-KMS) 加密，請務必在存取 S3 儲存貯體時授予使用金鑰的 AWS 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.aws.amazon.com//iot/latest/developerguide/iot-create-rule.html)以供使用 [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) SQL 函數來解碼 protobuf 訊息承載格式。詳細的函數簽章和範例可參見 *AWS 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`。
完成組態後，請在規則訂閱的主題 AWS IoT Core 上發佈訊息至 。
### 限制
AWS IoT Core 規則支援具有下列限制的 protobuf：
+ 不支援在[替代範本](https://docs.aws.amazon.com//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 儲存貯體中備份原型檔案。
理想的做法是備份 proto 檔案以防患未然。例如，如果在執行 protoc 時錯誤地修改了沒有備份的原型檔案，這可能會導致生產堆疊發生問題。有多種方法在 Amazon S3 儲存貯體中備份檔案 例如，您可以[在 S3 儲存貯體中使用版本控制](https://docs.aws.amazon.com//AmazonS3/latest/userguide/Versioning.html)。如需有關如何備份 Amazon S3 儲存貯體中檔案的詳細資訊，請參閱 *[Amazon S3 開發人員指南](https://docs.aws.amazon.com//aws-backup/latest/devguide/recovery-points.html)*。
+ 設定 AWS IoT 記錄以檢視日誌項目。
設定 AWS IoT 記錄是很好的做法，讓您可以在 CloudWatch 中檢查帳戶的 AWS IoT 日誌。當規則的 SQL 查詢呼叫外部 函數時， AWS IoT Core Rules 會產生具有 之 `eventType`的日誌項目`FunctionExecution`，其中包含可協助您對失敗進行疑難排解的原因欄位。可能的錯誤包括找不到 Amazon S3 物件，或是 protobuf 檔案描述項無效。如需進一步了解如何設定 AWS IoT 記錄及查看日誌項目，請參閱[設定 AWS IoT 記錄](https://docs.aws.amazon.com//iot/latest/developerguide/configure-logging.html)和[規則引擎日誌項目](https://docs.aws.amazon.com//iot/latest/developerguide/cwl-format.html#log-rules-fn-exec)。
+ 使用新的物件索引鍵來更新 `FileDescriptorSet` 以及更新規則中的物件索引鍵。
您可以將更新後的描述項檔案上傳到 Amazon S3 儲存貯體來更新 `FileDescriptorSet`。系統可能需要最多 15 分鐘的時間來反映 `FileDescriptorSet` 的更新作業。為了避免這種延遲，理想做法是使用新的物件索引鍵上傳更新後的 `FileDescriptorSet`，並在規則中更新物件索引鍵。
# SQL 版本
AWS IoT 規則引擎使用類似 SQL 的語法，從 MQTT 訊息中選取資料。SQL 陳述式會以指定的 SQL 版本來解釋，版本由描述規則的 JSON 文件的 `awsIotSqlVersion` 屬性指定。如需更多關於 JSON 規則文件結構的資訊，請參閱[建立規則的相關文章](iot-create-rule.md)。`awsIotSqlVersion` 屬性可讓您指定要使用的 AWS 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"
}
}]
}
```
AWS IoT 目前支援下列 SQL 版本：
+ `2016-03-23`：建立於 2016 年 3 月 23 日的 SQL 版本（推薦）。
+ `2015-10-08`：建立於 2015 年 10 月 8 日的原始 SQL 版本。
+ `beta`：最新的 SQL 版本。此版本可能導致規則受到中段變更。
## 2016 年 3 月 23 日 SQL 規則引擎版本的新功能
+ 修正巢狀 JSON 物件的選取問題。
+ 修正陣列查詢的問題。
+ 支援物件內部查詢。如需詳細資訊，請參閱[巢狀物件查詢](iot-sql-nested-queries.md)。
+ 支援將陣列輸出為最上層物件。
+ 除了 `encode(value, encodingScheme)` 函數外，它也可以應用於 JSON 和非 JSON 格式資料。如需詳細資訊，請參閱[編碼函數](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]
```