JSON-platmaken, escapen en matrixafhandeling

  • Artikel

Notitie

De Time Series Insights-service (TSI) wordt na maart 2025 niet meer ondersteund. Overweeg om bestaande TSI-omgevingen zo snel mogelijk naar alternatieve oplossingen te migreren. Raadpleeg onze documentatie voor meer informatie over de afschaffing en migratie.

Uw Azure Time Series Insights Gen2-omgeving maakt dynamisch de kolommen van uw warme en koude opslag, volgens een bepaalde set naamconventies. Wanneer een gebeurtenis wordt opgenomen, wordt een set regels toegepast op de JSON-nettolading en eigenschapsnamen. Dit zijn onder andere het ontsnappen van bepaalde speciale tekens en het platmaken van geneste JSON-objecten. Het is belangrijk om deze regels te kennen, zodat u begrijpt hoe de vorm van uw JSON van invloed is op hoe uw gebeurtenissen worden opgeslagen en opgevraagd. Zie de onderstaande tabel voor de volledige lijst met regels. Voorbeelden A & B laten ook zien hoe u efficiënt meerdere tijdreeksen in een matrix kunt batcheren.

Belangrijk

  • Bekijk de onderstaande regels voordat u een eigenschap Time Series ID en/of de juiste tijdstempels voor de gebeurtenisbron selecteert. Als uw TS-id of -tijdstempel zich in een genest object bevindt of een of meer van de onderstaande speciale tekens bevat, is het belangrijk om ervoor te zorgen dat de eigenschapsnaam die u opgeeft overeenkomt met de kolomnaam nadat de opnameregels zijn toegepast. Zie voorbeeld B hieronder.
Regel Voorbeeld van JSON Syntaxis van tijdreeksexpressie Kolomnaam van eigenschap in Parquet
Het gegevenstype Azure Time Series Insights Gen2 wordt toegevoegd aan het einde van de kolomnaam als _<dataType> "type": "Accumulated Heat" $event.type.String type_string
De eigenschap tijdstempel van de gebeurtenisbron wordt opgeslagen in Azure Time Series Insights Gen2 als tijdstempel in de opslag en de waarde die is opgeslagen in UTC. U kunt de tijdstempeleigenschap van uw gebeurtenisbron(s) aanpassen aan de behoeften van uw oplossing, maar de kolomnaam in warme en koude opslag is 'tijdstempel'. Andere JSON-eigenschappen voor datum/tijd die niet de tijdstempel van de gebeurtenisbron zijn, worden opgeslagen met '_datetime' in de kolomnaam, zoals vermeld in de bovenstaande regel. "ts": "2020-03-19 14:40:38.318" $event.$ts timestamp
JSON-eigenschapsnamen die de speciale tekens bevatten. [ \ en ' zijn ontsnapt met [' en '] "id.wasp": "6A3090FD337DE6B" $event['id.wasp'].String ['id.wasp']_string
Binnen [' en '] zijn er extra escapes van enkele aanhalingstekens en backslashes. Eén aanhalingsteken wordt geschreven als \' en er wordt een backslash geschreven als \\ "Foo's Law Value": "17.139999389648" $event['Foo\'s Law Value'].Double ['Foo\'s Law Value']_double
Geneste JSON-objecten worden afgevlakt met een punt als scheidingsteken. Het nesten van maximaal 10 niveaus wordt ondersteund. "series": {"value" : 316 } $event.series.value.Long, $event['series']['value'].Long of $event.series['value'].Long series.value_long
Matrices van primitieve typen worden opgeslagen als dynamisch type "values": [154, 149, 147] Dynamische typen kunnen alleen worden opgehaald via de GetEvents-API values_dynamic
Matrices met objecten hebben twee gedragingen, afhankelijk van de objectinhoud: als de TS-id('s) of tijdstempeleigenschap(en) zich binnen de objecten in een matrix bevinden, wordt de matrix uitgeschreven, zodat de initiële JSON-nettolading meerdere gebeurtenissen produceert. Hiermee kunt u meerdere gebeurtenissen in één JSON-structuur batcheren. Alle eigenschappen op het hoogste niveau die peers met de matrix zijn, worden opgeslagen met elk niet-ingeschreven object. Als uw TS-id('s) en tijdstempel zich niet in de matrix bevinden, wordt deze geheel opgeslagen als het dynamische type. Zie de voorbeelden A, B en C hieronder
Matrices met gemengde elementen worden niet afgevlakt. "values": ["foo", {"bar" : 149}, 147] Dynamische typen kunnen alleen worden opgehaald via de GetEvents-API values_dynamic
512 tekens is de naamlimiet van de JSON-eigenschap. Als de naam langer is dan 512 tekens, wordt deze afgekapt tot 512 en wordt '_<'hashCode>' toegevoegd. Houd er rekening mee dat dit ook van toepassing is op eigenschapsnamen die zijn samengevoegd van objecten die zijn afgevlakt, wat een geneste objectpad aangeeft. "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

Inzicht in het dubbele gedrag voor matrices

Matrices van objecten worden geheel opgeslagen of gesplitst in meerdere gebeurtenissen, afhankelijk van hoe u uw gegevens hebt gemodelleerd. Hiermee kunt u een matrix gebruiken om gebeurtenissen te batcheren en te voorkomen dat er herhalende telemetrie-eigenschappen worden gedefinieerd op het niveau van het hoofdobject. Batchverwerking kan voordelig zijn omdat dit resulteert in minder Event Hubs- of IoT Hub-berichten die worden verzonden.

In sommige gevallen zijn matrices met objecten echter alleen zinvol in de context van andere waarden. Als u meerdere gebeurtenissen maakt, worden de gegevens betekenisloos weergegeven. Als u ervoor wilt zorgen dat een matrix met objecten als dynamisch type wordt opgeslagen, volgt u de onderstaande richtlijnen voor gegevensmodellering en bekijkt u voorbeeld C

Hoe weet ik of mijn matrix met objecten meerdere gebeurtenissen produceert

Als een of meer van uw time series-id's zijn genest binnen objecten in een matrix of als de eigenschap van de tijdstempel van de gebeurtenisbron is genest, wordt deze door de opname-engine gesplitst om meerdere gebeurtenissen te maken. De eigenschapsnamen die u hebt opgegeven voor uw TS-id('s) en/of tijdstempel, moeten de bovenstaande afvlakkende regels volgen en geven daarom de vorm van uw JSON aan. Zie de onderstaande voorbeelden en bekijk de handleiding voor het selecteren van een time series-id-eigenschap.

Voorbeeld A

Tijdreeks-id in de hoofdmap en tijdstempel genest van het object
Omgevingstijdreeks-id:"id"
Tijdstempel van gebeurtenisbron:"values.time"
JSON-nettolading:

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

Resultaat in Parquet-bestand:
De configuratie en nettolading hierboven produceren drie kolommen en vier gebeurtenissen

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

Voorbeeld B

Samengestelde tijdreeks-id met één eigenschap genest
Omgevingstijdreeks-id:"plantId" en "telemetry.tagId"
Tijdstempel van gebeurtenisbron:"timestamp"
JSON-nettolading:

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

Resultaat in Parquet-bestand:
De configuratie en nettolading hierboven produceren vier kolommen en zes gebeurtenissen

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

Voorbeeld C

Tijdreeks-id en tijdstempel bevinden zich in de hoofdmap van het object
Omgevingstijdreeks-id:"id"
Tijdstempel van gebeurtenisbron:"timestamp"
JSON-nettolading:

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

Resultaat in Parquet-bestand:
De bovenstaande configuratie en nettolading produceren drie kolommen en één gebeurtenis

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

Volgende stappen