JSON フラット化、エスケープ、および配列処理

[アーティクル]
01/21/2021

手記

Time Series Insights サービスは、2024 年 7 月 7 日に廃止されます。既存の環境をできるだけ早く別のソリューションに移行することを検討してください。非推奨と移行の詳細については、ドキュメントを参照してください。

Azure Time Series Insights Gen2 環境では、特定の名前付け規則のセットに従って、ウォームストアとコールドストアの列が動的に作成されます。イベントが取り込まれると、一連のルールが JSON ペイロードとプロパティ名に適用されます。これには、特定の特殊文字のエスケープや、入れ子になった JSON オブジェクトのフラット化が含まれます。 JSON の形状がイベントの格納とクエリの方法に与える影響を理解できるように、これらのルールを理解しておくことが重要です。ルールの完全な一覧については、次の表を参照してください。例 A & B は、配列内の複数の時系列を効率的にバッチ処理する方法も示しています。

大事な

Time Series ID プロパティおよび/またはイベントソースのタイムスタンププロパティを選択する前に、以下の規則を確認してください。 TS ID またはタイムスタンプが入れ子になったオブジェクト内にある場合、または以下の特殊文字が 1 つ以上含まれている場合は、インジェストルールが適用後に、指定したプロパティ名が列名と一致していることを確認することが重要です。以下の B 例を参照してください。

規則	JSON の例	時系列表現構文の	Parquet のプロパティ列名
Azure Time Series Insights Gen2 データ型は、列名の末尾に "_<dataType>" として追加されます	`"type": "Accumulated Heat"`	`$event.type.String`	`type_string`
イベントソースタイムスタンププロパティは、ストレージの "timestamp" として Azure Time Series Insights 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`
オブジェクトを含む配列には、オブジェクトの内容に応じて 2 つの動作があります。TS ID または timestamp プロパティのいずれかが配列内のオブジェクト内にある場合、最初の JSON ペイロードで複数のイベントが生成されるように、配列は展開解除されます。これにより、複数のイベントを 1 つの JSON 構造にバッチ処理できます。配列と同レベルにある最上位のプロパティは、展開された各オブジェクトと共に保存されます。 TS ID およびタイムスタンプが配列内でではなくの場合、全体が動的型として保存されます。	以下の例 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`

配列のデュアル動作について

オブジェクトの配列は、データのモデル化方法に応じて、全体または複数のイベントに分割されます。これにより、配列を使用してイベントをバッチ処理し、ルートオブジェクトレベルで定義されているテレメトリプロパティの繰り返しを回避できます。バッチ処理は、送信される Event Hubs または IoT Hub メッセージが少なくなり、有利な場合があります。

ただし、場合によっては、オブジェクトを含む配列は、他の値のコンテキストでのみ意味があります。複数のイベントを作成すると、データは無意味になります。オブジェクトの配列が動的な型として as-is 格納されるようにするには、以下のデータモデリングガイダンスに従って、サンプル C 見てみましょう

オブジェクトの配列が複数のイベントを生成するかどうかを知る方法

1 つ以上の Time Series 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 ファイルにおける結果:
上記の構成とペイロードでは、3 つの列と 4 つのイベントが生成されます

タイムスタンプ	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

入れ子にされた1つのプロパティを持つ複合時系列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 ファイルの結果:
上記の構成とペイロードでは、4 つの列と 6 つのイベントが生成されます

タイムスタンプ	plantId_string	telemetry.tagId_string	テレメトリー.値_ダブル
`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 ファイルでの結果:
上記の構成とペイロードにより、3 つの列と 1 つのイベントが生成されます

タイムスタンプ	id_string	データポイント_ダイナミック
`2020-11-01T10:00:00.000Z`	`800500054755`	`[{"value": 120},{"value":124}]`

次の手順

環境のスループットの制限を理解する

次の方法で共有

JSON フラット化、エスケープ、および配列処理

配列のデュアル動作について

オブジェクトの配列が複数のイベントを生成するかどうかを知る方法

例 A

例 B

例 C

次の手順

その他のリソース