本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
Timestream
Timestream 规则操作将 MQTT 消息中的属性(度量)写入 Amazon Timestream 表。有关 Amazon Timestream 的更多信息,请参阅什么是 Amazon Timestream?。
注意
Amazon Timestream 并未在所有Amazon Web Services 区域中推出。如果 Amazon Timestream 在您所在区域中不可用,则它将不会显示在规则操作列表中。
此规则存储在 Timestream 数据库中的属性是由规则的查询语句生成的属性。对查询语句结果中每个属性的值进行解析以推断其数据类型(如 DynamoDBv2 操作)。每个属性的值都写入到 Timestream 表中自己的记录中。要指定或更改属性的数据类型,请在查询语句中使用 cast() 函数。有关每条 Timestream 记录内容的更多信息,请参阅 Amazon Timestream 记录内容。
注意
对于 SQL V2 (2016-03-23),整数数字值,例如 10.0
,将转换为整数表示形式 (10
)。显式将它们转换为 Decimal
值,例如通过使用 cast() 函数,不会阻止此行为——结果仍然是 Integer
值。这可能会导致类型不匹配错误,从而阻止在 Timestream 数据库中记录数据。若要可靠地将整数数值处理为 Decimal
值,请使用 SQL V1 (2015-10-08) 作为规则查询语句。
注意
Timestream 规则操作可以写入 Amazon Timestream 表的值的最大数目为 100。有关更多信息,请参阅 Amazon Timestream 配额参考。
要求
此规则操作具有以下要求:
-
Amazon IoT 可以承担以执行
timestream:DescribeEndpoints
和timestream:WriteRecords
操作的 IAM 角色。有关更多信息,请参阅向 Amazon IoT 规则授予所需的访问权限:在 Amazon IoT 控制台中,您可以选择、更新或创建一个角色以允许 Amazon IoT 以执行此规则操作。
-
如果使用客户托管的 Amazon Key Management Service (Amazon KMS) 加密 Timestream 中的静态数据,服务必须具有代表调用方使用 Amazon KMS key 的权限。有关更多信息,请参阅 Amazon 服务如何使用 Amazon KMS。
参数
使用此操作创建 Amazon IoT 规则时,您必须指定以下信息:
databaseName
-
Amazon Timestream 数据库的名称,该数据库中具有用于接收此操作创建的记录的表。另请参阅
tableName
。支持替换模板:仅限 API 和 Amazon CLI
dimensions
-
写入每个度量记录的时间序列的元数据属性。例如,EC2 实例的名称和可用区或风力涡轮机制造商的名称都是维度。
roleArn
-
角色的 Amazon Resource Name (ARN),该角色授予 Amazon IoT 写入 Timestream 数据库表的权限。有关更多信息,请参阅要求:
支持替换模板:否
tableName
-
要将度量记录写入的数据库表的名称。另请参阅
databaseName
。支持替换模板:仅限 API 和 Amazon CLI
timestamp
-
用于条目的时间戳的值。如果为空,则使用处理条目的时间。
unit
-
value
中描述的表达式生成的时间戳值的精度。有效值:
SECONDS
|MILLISECONDS
|MICROSECONDS
|NANOSECONDS
。默认为MILLISECONDS
。 value
-
返回长纪元时间值的表达式。
您可以使用 time_to_epoch(String, String) 函数从消息负载中传递的日期或时间值创建有效的时间戳。
Amazon Timestream 记录内容
通过此操作写入 Amazon Timestream 表的数据包括时间戳、Timestream 规则操作中的元数据以及规则查询语句的结果。
对于查询语句结果中的每个属性(度量),此规则操作将记录写入具有这些列的指定 Timestream 表。
列名称 |
属性类型 |
值 |
注释 |
---|---|---|---|
|
维度 |
在 Timestream 规则操作条目中指定的值。 |
每个维度都会在规则操作条目中指定的 Timestream 数据库中创建一个具有维度名称的列。 |
measure_name |
MEASURE_NAME |
属性的名称 |
查询语句结果中的属性名称,其值已在 |
measure_value:: |
MEASURE_VALUE |
查询语句结果中属性的值。属性的名称位于 |
该值被解释* 并转换为最佳匹配: |
time |
TIMESTAMP |
数据库中记录的日期和时间。 |
此值由规则引擎或 |
* 从消息负载读取的属性值解释如下。请参阅 示例,了解各个案例的说明。
-
一个无引号的
true
或者false
值将被解释为boolean
类型。 -
十进制数字被解释为
double
类型。 -
没有小数点的数值被解释为
bigint
类型。 -
带引号的字符串被解释为
varchar
类型。 -
对象和数组值将转换为 JSON 字符串并存储为
varchar
类型。
示例
以下 JSON 示例定义了 Amazon IoT 规则内包含替换模板的 Timestream 规则操作。
{ "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_firmware_sku | device_id | measure_name | measure_value::bigint | measure_value::varchar | measure_value::double | measure_value::boolean | time |
---|---|---|---|---|---|---|---|
我的静态元数据 | iotconsole-159EXAMPLE738-0 | complex_value | - | {"simple_element":42,"array_of_integers":[23,36,56,72],"array of strings":["red","green","blue"]} | - | - | 2020-08-26 22:42:16.423000000 |
我的静态元数据 | iotconsole-159EXAMPLE738-0 | integer_value_as_string | - | 123456789012 | - | - | 2020-08-26 22:42:16.423000000 |
我的静态元数据 | iotconsole-159EXAMPLE738-0 | boolean_value | - | - | - | TRUE | 2020-08-26 22:42:16.423000000 |
我的静态元数据 | iotconsole-159EXAMPLE738-0 | integer_value | 123456789012 | - | - | - | 2020-08-26 22:42:16.423000000 |
我的静态元数据 | iotconsole-159EXAMPLE738-0 | string_value | - | 字符串值 | - | - | 2020-08-26 22:42:16.423000000 |
我的静态元数据 | iotconsole-159EXAMPLE738-0 | array_of_integers | - | [23,36,56,72] | - | - | 2020-08-26 22:42:16.423000000 |
我的静态元数据 | iotconsole-159EXAMPLE738-0 | 字符串数组 | - | ["red","green","blue"] | - | - | 2020-08-26 22:42:16.423000000 |
我的静态元数据 | iotconsole-159EXAMPLE738-0 | boolean_value_as_string | - | TRUE | - | - | 2020-08-26 22:42:16.423000000 |
我的静态元数据 | iotconsole-159EXAMPLE738-0 | double_value | - | - | 123.456789012 | - | 2020-08-26 22:42:16.423000000 |
我的静态元数据 | iotconsole-159EXAMPLE738-0 | double_value_as_string | - | 123.45679 | - | - | 2020-08-26 22:42:16.423000000 |