本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 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 |