JSON-platmaken, escapen en matrixafhandeling

Artikel
10/26/2023

Notitie

De Time Series Insights-service wordt op 7 juli 2024 buiten gebruik gesteld. Overweeg om bestaande 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

Inzicht in de doorvoerbeperkingen van uw omgeving

Delen via