Freigeben über

JSON-Flattening, Escaping und Arraybehandlung

  • Artikel

Anmerkung

Der Time Series Insights-Dienst wird am 7. Juli 2024 eingestellt. Erwägen Sie, vorhandene Umgebungen so schnell wie möglich zu alternativen Lösungen zu migrieren. Weitere Informationen zur Abschaffung und zur Migration finden Sie in der Dokumentation.

Ihre Azure Time Series Insights Gen2-Umgebung wird dynamisch die Spalten Ihrer Warm- und Kaltspeicher gemäß einer bestimmten Reihe von Benennungskonventionen erstellen. Wenn ein Ereignis aufgenommen wird, wird eine Reihe von Regeln auf die JSON-Nutzlast und die Eigenschaftennamen angewendet. Dazu gehören das Maskieren bestimmter Sonderzeichen und das Abflachen geschachtelter JSON-Objekte. Es ist wichtig, diese Regeln zu kennen, damit Sie verstehen, wie die Form Ihres JSON-Codes beeinflusst, wie Ihre Ereignisse gespeichert und abgefragt werden. Die vollständige Liste der Regeln finden Sie in der folgenden Tabelle. Beispiele A & B veranschaulichen außerdem, wie Sie mehrere Zeitreihen in einem Array effizient stapeln können.

Wichtig

  • Überprüfen Sie die folgenden Regeln, bevor Sie eine Eigenschaft der Zeitreihenkennung und/oder Ihre Ereignisquelle Zeitstempel-Eigenschaft(en)auswählen. Wenn sich die TS-ID oder der Zeitstempel innerhalb eines geschachtelten Objekts befindet oder mindestens eines der unten aufgeführten Sonderzeichen enthält, müssen Sie sicherstellen, dass der von Ihnen angegebene Name der Eigenschaft mit dem Spaltennamen übereinstimmt, nachdem die Aufnahmeregeln angewendet wurden. Siehe Beispiel B unten.
Regel Beispiel-JSON Syntax des Zeitreihen-Ausdrucks Name der Eigenschaftsspalte in Parquet
Der Datentyp "Azure Time Series Insights Gen2" wird am Ende des Spaltennamens als "_<dataType>" angefügt. "type": "Accumulated Heat" $event.type.String type_string
Die Eigenschaft des Zeitstempels der Ereignisquelle wird in Azure Time Series Insights Gen2 als "Zeitstempel" gespeichert, und der Wert wird in UTC gespeichert. Sie können Ihre Ereignisquellen-Zeitstempel-Eigenschaft an die Anforderungen Ihrer Lösung anpassen, aber der Spaltenname im warmen und kalten Speicher lautet "Zeitstempel". Andere Datetime-JSON-Eigenschaften, die nicht der Zeitstempel der Ereignisquelle sind, werden mit "_datetime" im Spaltennamen gespeichert, wie in der obigen Regel erwähnt. "ts": "2020-03-19 14:40:38.318" $event.$ts timestamp
JSON-Eigenschaftsnamen, die die Sonderzeichen enthalten. [ \ und ' werden durch [' und '] maskiert "id.wasp": "6A3090FD337DE6B" $event['id.wasp'].String ['id.wasp']_string
Innerhalb von [' und '] gibt es ein zusätzliches Escaping von einzelnen Anführungszeichen und umgekehrten Schrägstrichen. Ein einzelnes Anführungszeichen wird als \' dargestellt, und ein Backslash wird als \\ dargestellt. "Foo's Law Value": "17.139999389648" $event['Foo\'s Law Value'].Double ['Foo\'s Law Value']_double
Geschachtelte JSON-Objekte werden mit einem Punkt als Trennzeichen in eine flache Form gebracht. Das Schachteln von bis zu 10 Ebenen wird unterstützt. "series": {"value" : 316 } $event.series.value.Long, $event['series']['value'].Long oder $event.series['value'].Long series.value_long
Arrays von Grundtypen werden als dynamischer Typ gespeichert. "values": [154, 149, 147] Dynamische Typen können nur über die GetEvents-API abgerufen werden. values_dynamic
Arrays, die Objekte enthalten, verhalten sich je nach Inhalt der Objekte auf zwei Arten: Wenn entweder die TS-IDs oder die Timestamp-Eigenschaften innerhalb der Objekte in einem Array vorhanden sind, wird das Array entrollt, sodass die anfängliche JSON-Nutzlast mehrere Ereignisse erstellt. Auf diese Weise können Sie mehrere Ereignisse in eine JSON-Struktur bündeln. Alle Eigenschaften der obersten Ebene, die Peers zum Array sind, werden mit jedem nichtrollierten Objekt gespeichert. Wenn Ihre TS-IDs und Zeitstempel nicht im Array sind, werden sie alle vollständig als dynamischer Typ gespeichert. Beispiele A, Bund C- unten
Arrays, die gemischte Elemente enthalten, werden nicht abgeflacht. "values": ["foo", {"bar" : 149}, 147] Dynamische Typen können nur über die GetEvents-API abgerufen werden. values_dynamic
512 Zeichen ist der JSON-Eigenschaftsnamengrenzwert. Wenn der Name 512 Zeichen überschreitet, wird er auf 512 Zeichen abgeschnitten und '_<'hashCode'>' angefügt. Beachten Sie, dass dies auch für Eigenschaftsnamen gilt, die durch das Abflachen von Objekten entstanden sind und einen verschachtelten Objektpfad darstellen. "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

Verständnis des dualen Verhaltens von Arrays

Arrays von Objekten werden entweder vollständig gespeichert oder in mehrere Ereignisse aufgeteilt, je nachdem, wie Sie Ihre Daten modelliert haben. Auf diese Weise können Sie ein Array verwenden, um Ereignisse zu stapeln und wiederholte Telemetrieeigenschaften zu vermeiden, die auf der Stammobjektebene definiert sind. Die Verwendung von Batching kann vorteilhaft sein, da dadurch weniger Nachrichten über Event Hubs oder IoT Hub gesendet werden.

In einigen Fällen sind Arrays, die Objekte enthalten, jedoch nur im Kontext anderer Werte aussagekräftig. Das Erstellen mehrerer Ereignisse würde die Daten bedeutungslos rendern. Um sicherzustellen, dass ein Array von Objekten as-is als dynamischer Typ gespeichert wird, befolgen Sie die folgende Anleitung zur Datenmodellierung und sehen Sie sich Beispiel C an.

Wie man herausfindet, ob mein Array von Objekten mehrere Ereignisse erzeugt

Wenn eine oder mehrere Ihrer Zeitreihen-ID-Eigenschaft(en) in Objekten innerhalb eines Arrays geschachtelt sind, oder bzw., wenn die Zeitstempeleigenschaft der Ereignisquelle geschachtelt ist, wird die Ingestions-Engine diese aufteilen, um mehrere Ereignisse zu erstellen. Die Eigenschaftennamen, die Sie für Ihre TS-ID(n) und/oder den Zeitstempel angegeben haben, sollten den oben beschriebenen Flachungsregeln entsprechen und daher die Form Ihres JSON-Codes angeben. Sehen Sie sich die folgenden Beispiele an, und sehen Sie sich die Anleitung an, wie Sie eine Id-Eigenschaft für Zeitreihen auswählen.

Beispiel A

Zeitreihen-ID im Objektstamm und im geschachtelten Zeitstempel
Umweltzeitsreihe-ID:"id"
Ereignisquellzeitstempel:"values.time"
JSON-Nutzlast:

[
    {
        "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
            }
        ]
    }
]

Ergebnis in der Parquet-Datei:
Die oben aufgeführte Konfiguration und Nutzlast erzeugen drei Spalten und vier Ereignisse.

Zeitstempel 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

Beispiel B

Zusammengesetzte Zeitreihen-ID mit einer verschachtelten Eigenschaft
Umgebungszeitreihen-ID:"plantId" und "telemetry.tagId"
Ereignisquellzeitstempel:"timestamp"
JSON-Nutzlast:

[
    {
        "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
            }
        ]
    }
]

Ergebnis in Parquet-Datei:
Die oben aufgeführte Konfiguration und Nutzlast erzeugen vier Spalten und sechs Ereignisse.

Zeitstempel plantId_string telemetry.tagId_string telemetrie.wert_doppel
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

Beispiel C

Zeitreihen-ID und Zeitstempel befinden sich im Objektstamm
Umgebungszeitreihen-ID:"id"
Ereignisquellzeitstempel:"timestamp"
JSON-Nutzlast:

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

Ergebnis in Parquet-Datei:
Die oben aufgeführte Konfiguration und Nutzlast erzeugen drei Spalten und ein Ereignis.

Zeitstempel id_string dynamische Datenpunkte
2020-11-01T10:00:00.000Z 800500054755 [{"value": 120},{"value":124}]

Nächste Schritte