JSON 扁平化、转义和数组处理

项目
01/21/2021

注意

时序见解服务将于 2024 年 7 月 7 日停用。请考虑尽快将现有环境迁移到备用解决方案。有关弃用和迁移的详细信息，请访问我们的文档。

Azure 时序见解 Gen2 环境将按照一组特定的命名约定动态生成暖存储和冷存储的列。当事件被引入时，将一组规则应用于 JSON 负载和属性名称。其中包括转义某些特殊字符和简化嵌套的 JSON 对象。请务必了解这些规则，以便了解 JSON 的形状如何影响事件存储和查询的方式。有关规则的完整列表，请参阅下表。示例 A & B 还演示了如何在数组中有效地对多个时序进行批处理。

重要

在选择时序 ID 属性和/或事件源时间戳属性之前，请查看以下规则。如果 TS ID 或时间戳位于嵌套对象中，或具有以下一个或多个特殊字符，请务必确保在应用引入规则后提供的属性名称与列名匹配。请参阅下面的示例 B。

规则	示例 JSON	时序表达式语法	Parquet 中的属性列名称
Azure 时序见解 Gen2 数据类型会追加到列名的末尾，形式为“_<dataType>”	`"type": "Accumulated Heat"`	`$event.type.String`	`type_string`
事件源的时间戳属性将作为“时间戳”保存在 Azure 时序见解 Gen2 的存储中，其值将以 UTC 格式存储。可以自定义事件源时间戳属性以满足解决方案的需求，但暖存储和冷存储中的列名称为“timestamp”。其他非事件源时间戳的日期/时间 JSON 属性将以列名称中的“_datetime”保存，如上述规则中所述。	`"ts": "2020-03-19 14:40:38.318"`	`$event.$ts`	`timestamp`
包含特殊字符的 JSON 属性名称。 [ \ 和 ' 被转义为 [' 和 ']	`"id.wasp": "6A3090FD337DE6B"`	`$event['id.wasp'].String`	`['id.wasp']_string`
在 [' 和 '] 中，单引号和反斜杠有额外的转义处理。单个引号将写为 \'，反斜杠将写为 \\	`"Foo's Law Value": "17.139999389648"`	`$event['Foo\'s Law Value'].Double`	`['Foo\'s Law Value']_double`
嵌套的 JSON 对象会被展开，使用句点作为分隔符。最多支持嵌套 10 个级别。	`"series": {"value" : 316 }`	`$event.series.value.Long`、`$event['series']['value'].Long` 或 `$event.series['value'].Long`	`series.value_long`
基元类型的数组存储为动态类型	`"values": [154, 149, 147]`	只能通过 GetEvents API 检索动态类型	`values_dynamic`
包含对象的数组根据对象内容有两种行为：如果数组中的对象包含 TS ID 或时间戳属性，数组将展开，从而使初始 JSON 负载生成多个事件。这样，便可以将多个事件批处理到一个 JSON 结构中。与数组并列的任何顶级属性都将与每个展开的对象一起保存。如果 TS ID（s）和时间戳不在数组中而非，则会将其完整保存为动态类型。	请参阅下面的示例 A、B和 C
包含混合元素的数组不会展开。	`"values": ["foo", {"bar" : 149}, 147]`	只能通过 GetEvents API 检索动态类型	`values_dynamic`
512 个字符是 JSON 属性名称限制。如果名称超过 512 个字符，则会将其截断为 512，并追加“_<”hashCode“>”。注意，这也适用于通过对象扁平化后连接的属性名称，表示嵌套的对象路径。	`"data.items.datapoints.values.telemetry<...continuing to over 512 chars>" : 12.3440495`	`"$event.data.items.datapoints.values.telemetry<...continuing to include all chars>.Double"`	`data.items.datapoints.values.telemetry<...continuing to 512 chars>_912ec803b2ce49e4a541068d495ab570_double`

了解数组的双重行为

对象数组将全部存储或拆分为多个事件，具体取决于数据建模方式。这样就可以使用数组对事件进行批处理，并避免重复在根对象级别定义的遥测属性。批处理可能很有利，因为它导致发送的事件中心或 IoT 中心消息更少。

但是，在某些情况下，包含对象的数组仅在其他值的上下文中有意义。创建多个事件会使数据毫无意义。若要确保对象数组作为动态类型存储 as-is，请遵循下面的数据建模指南并查看示例 C

如何知道我的对象数组是否会生成多个事件

如果一个或多个时序 ID 属性嵌套在数组中的对象中，有或表示事件源时间戳属性的嵌套，则导入引擎会将其拆分以创建多个事件。为 TS ID 和/或时间戳提供的属性名称应遵循上述平展规则，因此将指示 JSON 的形状。请参阅以下示例，并查看有关如何选择时序 ID 属性的指南。

示例 A

对象根和嵌套时间戳处的时序 ID
环境时序 ID："id"
事件源时间戳："values.time"
JSON 数据负载：

[
    {
        "id": "caaae533-1d6c-4f58-9b75-da102bcc2c8c",
        "values": [
            {
                "time": "2020-05-01T00:59:59.000Z",
                "value": 25.6073
            },
            {
                "time": "2020-05-01T01:00:29.000Z",
                "value": 43.9077
            }
        ]
    },
    {
        "id": "1ac87b74-0865-4a07-b512-56602a3a576f",
        "values": [
            {
                "time": "2020-05-01T00:59:59.000Z",
                "value": 0.337288
            },
            {
                "time": "2020-05-01T01:00:29.000Z",
                "value": 4.76562
            }
        ]
    }
]

Parquet 文件中的结果：
上述配置和有效负载将生成三列和四个事件

时间戳	id_string	values.value_double
`2020-05-01T00:59:59.000Z`	`caaae533-1d6c-4f58-9b75-da102bcc2c8c`	`25.6073`
`2020-05-01T01:00:29.000Z`	`caaae533-1d6c-4f58-9b75-da102bcc2c8c`	`43.9077`
`2020-05-01T00:59:59.000Z`	`1ac87b74-0865-4a07-b512-56602a3a576f`	`0.337288`
`2020-05-01T01:00:29.000Z`	`1ac87b74-0865-4a07-b512-56602a3a576f`	`4.76562`

示例 B

包含一个嵌套属性的复合时间序列ID
环境时序 ID："plantId" 和 "telemetry.tagId"
事件源时间戳："timestamp"
JSON 数据载荷：

[
    {
        "plantId": "9336971",
        "timestamp": "2020-01-22T16:38:09Z",
        "telemetry": [
            {
                "tagId": "100231-A-A6",
                "tagValue": -31.149018
            },
            {
                "tagId": "100231-A-A1",
                "tagValue": 20.560796
            },
            {
                "tagId": "100231-A-A9",
                "tagValue": 177
            },
            {
                "tagId": "100231-A-A8",
                "tagValue": 420
            },
        ]
    },
    {
        "plantId": "9336971",
        "timestamp": "2020-01-22T16:42:14Z",
        "telemetry": [
            {
                "tagId": "103585-A-A7",
                "value": -30.9918
            },
            {
                "tagId": "103585-A-A4",
                "value": 19.960796
            }
        ]
    }
]

Parquet 文件中的结果：
上述配置和有效负载将生成四列和六个事件

时间戳	plantId_string	telemetry.tagId_string（遥测.标签ID_字符串）	"遥测.值_双精度"
`2020-01-22T16:38:09Z`	`9336971`	`100231-A-A6`	-31.149018
`2020-01-22T16:38:09Z`	`9336971`	`100231-A-A1`	20.560796
`2020-01-22T16:38:09Z`	`9336971`	`100231-A-A9`	177
`2020-01-22T16:38:09Z`	`9336971`	`100231-A-A8`	420
`2020-01-22T16:42:14Z`	`9336971`	`100231-A-A7`	-30.9918
`2020-01-22T16:42:14Z`	`9336971`	`100231-A-A4`	19.960796

示例 C

时序 ID 和时间戳位于对象根目录中
环境时间序列 ID："id"
事件源时间戳："timestamp"
JSON 有效负载：

{
    "id": "800500054755",
    "timestamp": "2020-11-01T10:00:00.000Z",
    "datapoints": [{
            "value": 120
        },
        {
            "value": 124
        }
    ]
}

Parquet 文件中的结果：
上述配置和有效负载将生成三列和一个事件

时间戳	id字符串	动态数据点
`2020-11-01T10:00:00.000Z`	`800500054755`	`[{"value": 120},{"value":124}]`

后续步骤

了解环境的吞吐量限制

通过