JSON 扁平化、轉義和陣列處理

備註

時間序列深入解析服務將於 2024 年 7 月 7 日淘汰。請考慮儘快將現有的環境移轉至替代解決方案。如需淘汰和移轉的詳細資訊，請瀏覽我們的檔。

您的 Azure 時間序列洞察 Gen2 會依照一組特定的命名慣例，動態建立熱和冷存放區的資料行。擷取事件時，會將一組規則套用至 JSON 承載和屬性名稱。其中包括逸出特定特殊字元和壓平合併巢狀 JSON 物件。請務必了解這些規則，以便您了解 JSON 的形狀如何影響事件儲存和查詢的方式。有關規則的完整清單，請參閱下表。範例 A 和 B 也會示範如何在陣列中有效率地批次處理多個時間序列。

這很重要

請先檢閱下列規則，再選取時間序列 ID 屬性和/或您的事件來源時間戳屬性。如果您的 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 屬性名稱。 [ \ 和 ' 是使用 [' 和 '] 逸出	`"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 識別碼或時間戳記屬性，則該陣列會展開，使初始 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 中樞訊息。

不過，在某些情況下，包含物件的陣列只有在其他值的內容中才有意義。建立多個事件會造成資料變得無意義。若要確保物件陣列 as-is 作為動態類型儲存，請遵循下列資料建模指導，並查看範例 C

如何知道我的物件陣列是否會產生多個事件

如果一個或多個時間序列識別碼屬性巢狀在陣列中的物件內，或如果您的事件來源時間戳記屬性是巢狀的，擷取引擎將會將其分割以創建多個事件。您為 TS ID 和/或時間戳記提供的屬性名稱應當遵循上述的展平規則，因此將會指出 JSON 的結構。請參閱下列範例，並查看如何選取時間序列標識符屬性的指南。

範例 A

物件根目錄的時間序列 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 檔案中的結果：
上述設定和承載會產生三個資料行和四個事件

時間戳	識別字串	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 檔案中的結果：
上述設定和承載會產生四個資料行和六個事件

時間戳	plantId_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"
事件來源時間戳："timestamp"
JSON 承載：

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

Parquet 檔案中的結果：
上述設定和承載會產生三個資料行和一個事件

時間戳	識別字串	動態數據點
`2020-11-01T10:00:00.000Z`	`800500054755`	`[{"value": 120},{"value":124}]`

後續步驟

了解環境的輸送量限制

Last updated on 2021-01-21

共用方式為