JSON 壓平合併、逸出和陣列處理
注意
時間序列深入解析 (TSI) 服務在 2025 年 3 月之後將不再受到支援。 請考慮儘快將現有的 TSI 環境移轉至替代解決方案。 如需淘汰和移轉的詳細資訊,請瀏覽我們的 檔。
您的 Azure 時間序列深入解析 Gen2 環境會依照一組特定的命名慣例,動態建立暖冷存放區的數據行。 擷取事件時,會將一組規則套用至 JSON 承載和屬性名稱。 這些包括逸出特定特殊字元和扁平化巢狀 JSON 物件。 請務必瞭解這些規則,以便您瞭解 JSON 的形狀如何影響事件儲存和查詢的方式。 如需規則的完整清單,請參閱下表。 範例 A 和 B 也會示範如何在數位中有效地批處理多個時間序列。
重要
- 請先檢閱下列規則,再選取時間序列標識符屬性和/或您的事件來源時間戳正確性(ies)。 如果您的 TS 識別碼或時間戳位於巢狀物件內,或下方有一或多個特殊字元,請務必確保套用擷取規則之後所提供的屬性名稱符合數據行名稱。 請參閱下面的範例 B 。
規則 | 範例 JSON | 時間序列表達式語法 | Parquet 中的屬性數據行名稱 |
---|---|---|---|
Azure 時間序列深入解析 Gen2 數據類型會附加至數據行名稱結尾作為 “_<dataType>” | "type": "Accumulated Heat" |
$event.type.String |
type_string |
事件來源時間戳屬性將會儲存在 Azure 時間序列深入解析 Gen2 中,作為記憶體中的「時間戳」,以及儲存在 UTC 中的值。 您可以自定義事件來源時間戳屬性以符合您的解決方案需求,但暖和冷記憶體中的數據行名稱為 「timestamp」。。 其他非事件來源時間戳的 datetime JSON 屬性將會以數據行名稱中的 「_datetime」 儲存,如上述規則所述。 | "ts": "2020-03-19 14:40:38.318" |
$event.$ts |
timestamp |
包含特殊字元的 JSON 屬性名稱。 [ \ and ' 是使用 [' 和 '] 逸出 | "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(s) 或 timestamp 屬性(ies) 位於陣列中的物件內,陣列將會取消註冊,讓初始 JSON 承載產生多個事件。 這可讓您將多個事件批處理成一個 JSON 結構。 與陣列對等的任何最上層屬性都會與每個未標籤的物件一起儲存。 如果您的 TS 識別碼和時間戳不在數位,則會將它儲存為動態類型。 | 請參閱下列範例 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 中樞 訊息。
不過,在某些情況下,包含對象的數位只有在其他值的內容中才有意義。 建立多個事件會讓數據變得毫無意義。 若要確保物件數位以動態類型的形式儲存,請遵循下列數據模型化指引,並查看 範例 C
如何知道我的物件陣列是否會產生多個事件
如果一或多個時間序列標識符 propert(ies) 巢狀在陣列中的物件內, 或 如果您的事件來源 timestamp 屬性是巢狀的,擷取引擎會分割它以建立多個事件。 您為 TS 識別碼和/或時間戳提供的屬性名稱應該遵循上述扁平化規則,因此會指出 JSON 的形狀。 請參閱下列範例,並查看如何 選取時間序列標識符屬性的指南。
範例 A
物件根目錄的時間序列標識元和巢狀時間戳
環境時間序列識別碼:"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 檔案:
上述組態和承載會產生三個數據行和四個事件
timestamp | 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
具有一個屬性巢狀的複合時間序列標識碼
環境時間序列標識碼:"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 檔案:
上述組態和承載會產生四個數據行和六個事件
timestamp | plantId_string | telemetry.tagId_string | telemetry.value_double |
---|---|---|---|
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"
事件來源時間戳:"timestamp"
JSON 承載:
{
"id": "800500054755",
"timestamp": "2020-11-01T10:00:00.000Z",
"datapoints": [{
"value": 120
},
{
"value": 124
}
]
}
導致 Parquet 檔案:
上述組態和承載會產生三個數據行和一個事件
timestamp | id_string | datapoints_dynamic |
---|---|---|
2020-11-01T10:00:00.000Z |
800500054755 |
[{"value": 120},{"value":124}] |
下一步
- 了解環境的 輸送量限制