本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # Timestream Timestream 规则操作将 MQTT 消息中的属性（度量）写入 Amazon Timestream 表。有关 Amazon Timestream 的更多信息，请参阅[什么是 Amazon Timestream？](https://docs.aws.amazon.com/timestream/latest/developerguide/what-is-timestream.html)。 **注意** Amazon Timestream 并非在所有版本中都 AWS 区域可用。如果 Amazon Timestream 在您所在区域中不可用，则它将不会显示在规则操作列表中。 此规则存储在 Timestream 数据库中的属性是由规则的查询语句生成的属性。对查询语句结果中每个属性的值进行解析以推断其数据类型（如 [迪纳摩 DBv2](dynamodb-v2-rule-action.md) 操作）。每个属性的值都写入到 Timestream 表中自己的记录中。要指定或更改属性的数据类型，请在查询语句中使用 [`cast()`](iot-sql-functions.md#iot-sql-function-cast) 函数。有关每条 Timestream 记录内容的更多信息，请参阅 [Timestream 记录内容](#timestream-rule-action-data)。 **注意** 对于 SQL V2（2016-03-23），整数数字值，例如 `10.0`，将转换为整数表示形式 (`10`)。显式将它们转换为 `Decimal` 值，例如通过使用 [cast()](iot-sql-functions.md#iot-sql-function-cast) 函数，不会阻止此行为--结果仍然是 `Integer` 值。这可能会导致类型不匹配错误，从而阻止在 Timestream 数据库中记录数据。要将整数数值处理为 `Decimal` 值，请使用 SQL V1（2015-10-08）作为规则查询语句。 **注意** Timestream 规则操作可以写入 Amazon Timestream 表的值的最大数目为 100。有关更多信息，请参阅 [Amazon Timestream 配额参考](https://docs.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)。 ## 参数 使用此操作创建 AWS IoT 规则时，必须指定以下信息： `databaseName` Amazon Timestream 数据库的名称，该数据库中具有用于接收此操作创建的记录的表。另请参阅`tableName`。 支持[替换模板](iot-substitution-templates.md)： AWS CLI 仅支持 API `dimensions` 写入每个度量记录的时间序列的元数据属性。例如，EC2 实例的名称和可用区或风力涡轮机制造商的名称都是维度。 `name` 元数据维度名称。这是数据库表记录中列的名称。 维度不能命名为：`measure_name`、`measure_value` 或者 `time`。这些是预留的名称。维度名称不能以 `ts_` 或者 `measure_value` 开头，并且它们不能包含冒号 (`:`) 字符。 支持[替换模板](iot-substitution-templates.md)：否 `value` 在数据库记录的此列中写入的值。 支持[替换模板](iot-substitution-templates.md)：是 `roleArn` 角色的 Amazon 资源名称（ARN），该角色授予 AWS IoT 写入 Timestream 数据库表的权限。有关更多信息，请参阅 [要求](#timestream-rule-action-requirements)。 支持[替换模板](iot-substitution-templates.md)：否 `tableName` 要将度量记录写入的数据库表的名称。另请参阅`databaseName`。 支持[替换模板](iot-substitution-templates.md)： AWS CLI 仅支持 API `timestamp` 用于条目的时间戳的值。如果为空，则使用处理条目的时间。 `unit` `value` 中描述的表达式生成的时间戳值的精度。 有效值：`SECONDS` \$1 `MILLISECONDS` \$1`MICROSECONDS` \$1 `NANOSECONDS`。默认值为 `MILLISECONDS`。 `value` 返回长纪元时间值的表达式。 您可以使用 [time\$1to\$1epoch(String, String)](iot-sql-functions.md#iot-sql-function-time-to-epoch) 函数从消息负载中传递的日期或时间值创建有效的时间戳。 ## Timestream 记录内容 通过此操作写入 Amazon Timestream 表的数据包括时间戳、Timestream 规则操作中的元数据以及规则查询语句的结果。 对于查询语句结果中的每个属性（度量），此规则操作将记录写入具有这些列的指定 Timestream 表。 | 列名称 | 属性类型 | 值 | 评论 | | --- | --- | --- | --- | | *dimension-name* | 维度 | 在 Timestream 规则操作条目中指定的值。 | 每个**维度**都会在规则操作条目中指定的 Timestream 数据库中创建一个具有维度名称的列。 | | measure\$1name | MEASURE\$1NAME | 属性的名称 | 查询语句结果中的属性名称，其值已在 `measure_value::data-type` 列。 | | 测量值:: *data-type* | MEASURE\$1VALUE | 查询语句结果中属性的值。属性的名称位于 `measure_name` 列。 | 该值被解释\$1 并强制转换为最合适的匹配：`bigint`、`boolean`、`double` 或 `varchar`。Amazon Timestream 为每种数据类型创建一个单独的列。消息中的值可以转换为另一个数据类型，方法是在规则的查询语句中使用 [`cast()`](iot-sql-functions.md#iot-sql-function-cast) 函数。 | | 时间 | TIMESTAMP | 数据库中记录的日期和时间。 | 此值由规则引擎或 `timestamp` 属性分配（如果已定义）。 | \$1 从消息有效载荷读取的属性值解释如下。请参阅 [示例](#timestream-rule-action-examples)，了解各个案例的说明。 + 一个无引号的 `true` 或者 `false` 值将被解释为 `boolean` 类型。 + 十进制数字被解释为 `double` 类型。 + 没有小数点的数值被解释为 `bigint` 类型。 + 带引号的字符串被解释为 `varchar` 类型。 + 对象和数组值将转换为 JSON 字符串并存储为 `varchar` 类型。 ## 示例 以下 JSON 示例定义了在规则中使用替换模板的 Timestream 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` 列是主题规则操作中定义的维度。Timestream 主题规则操作将创建 `time` 列以及 `measure_name` 和 `measure_value::*` 列，它将使用主题规则操作的查询语句结果中的值来填充这些值。 | device\$1firmware\$1sku | device\$1id | measure\$1name | measure\$1value::bigint | measure\$1value::varchar | measure\$1value::double | measure\$1value::boolean | 时间 | | --- | --- | --- | --- | --- | --- | --- | --- | | 我的静态元数据 | iotcon EXAMPLE738 sole-159 -0 | complex\$1value | - | \$1"simple\$1element":42,"array\$1of\$1integers":[23,36,56,72],"array of strings":["red","green","blue"]\$1 | - | - | 2020-08-26 22:42:16.423000000 | | 我的静态元数据 | iotcon EXAMPLE738 sole-159 -0 | integer\$1value\$1as\$1string | - | 123456789012 | - | - | 2020-08-26 22:42:16.423000000 | | 我的静态元数据 | iotcon EXAMPLE738 sole-159 -0 | boolean\$1value | - | - | - | TRUE | 2020-08-26 22:42:16.423000000 | | 我的静态元数据 | iotcon EXAMPLE738 sole-159 -0 | integer\$1value | 123456789012 | - | - | - | 2020-08-26 22:42:16.423000000 | | 我的静态元数据 | iotcon EXAMPLE738 sole-159 -0 | string\$1value | - | 字符串值 | - | - | 2020-08-26 22:42:16.423000000 | | 我的静态元数据 | iotcon EXAMPLE738 sole-159 -0 | array\$1of\$1integers | - | [23,36,56,72] | - | - | 2020-08-26 22:42:16.423000000 | | 我的静态元数据 | iotcon EXAMPLE738 sole-159 -0 | 字符串数组 | - | ["red","green","blue"] | - | - | 2020-08-26 22:42:16.423000000 | | 我的静态元数据 | iotcon EXAMPLE738 sole-159 -0 | boolean\$1value\$1as\$1string | - | TRUE | - | - | 2020-08-26 22:42:16.423000000 | | 我的静态元数据 | iotcon EXAMPLE738 sole-159 -0 | double\$1value | - | - | 123.456789012 | - | 2020-08-26 22:42:16.423000000 | | 我的静态元数据 | iotcon EXAMPLE738 sole-159 -0 | double\$1value\$1as\$1string | - | 123.45679 | - | - | 2020-08-26 22:42:16.423000000 |