Timestream - Amazon IoT Core
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

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) 作为规则查询语句。

Requirements

此规则操作具有以下要求:

  • Amazon IoT 可以承担以执行 timestream:DescribeEndpointstimestream:WriteRecords 操作的 IAM 角色。有关更多信息,请参阅 授予 Amazon IoT 所需的访问权限

    在 Amazon IoT 控制台中,您可以选择、更新或创建一个角色以允许 Amazon IoT 以执行此规则操作。

  • 如果您使用客户托管的 Amazon Key Management Service (Amazon KMS) 客户主密钥 (CMK) 对 Timestream 中的数据进行静态加密,则服务必须具有代表调用方使用 CMK 的权限。有关更多信息,请参阅 Amazon 服务如何使用 Amazon KMS

Parameters

使用此操作创建 Amazon IoT 规则时,您必须指定以下信息:

databaseName

Amazon Timestream 数据库的名称,该数据库中具有用于接收此操作创建的记录的表。另请参阅 tableName

支持替换模板:仅限 API 和 Amazon CLI

dimensions

写入每个度量记录的时间序列的元数据属性。例如,EC2 实例的名称和可用区或风力涡轮机制造商的名称都是维度。

name

元数据维度名称。这是数据库表记录中列的名称。

维度不能命名为:measure_namemeasure_value 或者 time。这些是预留的名称。维度名称不能以 ts_ 或者 measure_value 开头,并且它们不能包含冒号 (:) 字符。

支持替换模板:否

value

在数据库记录的此列中写入的值。

支持替换模板:是

roleArn

角色的 Amazon Resource Name (ARN),该角色授予 Amazon IoT 写入 Timestream 数据库表的权限。有关更多信息,请参阅 Requirements

支持替换模板:否

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::data-type 列。

measure_value::data-type

MEASURE_VALUE

查询语句结果中属性的值。属性的名称位于 measure_name 列。

该值被解释* 并转换为最佳匹配:bigintbooleandouble 或者 varchar。Amazon Timestream 为每种数据类型创建一个单独的列。消息中的值可以转换为另一个数据类型,方法是在规则的查询语句中使用 cast() 函数。

time

TIMESTAMP

数据库中记录的日期和时间。

此值由规则引擎或 timestamp 属性分配(如果已定义)。

* 从消息负载读取的属性值解释如下。请参阅 Examples,了解各个案例的说明。

  • 一个无引号的 true 或者 false 值将被解释为 boolean 类型。

  • 十进制数字被解释为 double 类型。

  • 没有小数点的数值被解释为 bigint 类型。

  • 带引号的字符串被解释为 varchar 类型。

  • 对象和数组值将转换为 JSON 字符串并存储为 varchar 类型。

Examples

以下 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_skudevice_id 列是主题规则操作中定义的维度。Timestream 主题规则操作将创建 time 列以及 measure_namemeasure_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