JSON-utplattning, undantag och matrishantering

Artikel
10/26/2023

Kommentar

Time Series Insights-tjänsten dras tillbaka den 7 juli 2024. Överväg att migrera befintliga miljöer till alternativa lösningar så snart som möjligt. Mer information om utfasning och migrering finns i vår dokumentation.

Din Azure Time Series Insights Gen2-miljö skapar dynamiskt kolumnerna i dina varma och kalla butiker, enligt en viss uppsättning namngivningskonventioner. När en händelse matas in tillämpas en uppsättning regler på JSON-nyttolasten och egenskapsnamnen. Dessa inkluderar att ta sig ur vissa specialtecken och platta ut kapslade JSON-objekt. Det är viktigt att känna till dessa regler så att du förstår hur formen på din JSON påverkar hur dina händelser lagras och efterfrågas. Se tabellen nedan för den fullständiga listan över regler. Exempel A &B visar också hur du effektivt kan batcha flera tidsserier i en matris.

Viktigt!

Granska reglerna nedan innan du väljer en time series-ID-egenskap och/eller tidsstämpeln för händelsekällan. Om ditt TS-ID eller tidsstämpel finns i ett kapslat objekt eller har ett eller flera specialtecken nedan är det viktigt att se till att egenskapsnamnet som du anger matchar kolumnnamnet efter att inmatningsreglerna har tillämpats. Se exempel B nedan.

Regel	Exempel på JSON	Syntax för Tidsserieuttryck	Egenskapskolumnnamn i Parquet
Datatypen Azure Time Series Insights Gen2 läggs till i slutet av kolumnnamnet som "_<dataType>"	`"type": "Accumulated Heat"`	`$event.type.String`	`type_string`
Tidsstämpelegenskapen för händelsekällan sparas i Azure Time Series Insights Gen2 som "tidsstämpel" i lagringen och värdet som lagras i UTC. Du kan anpassa din händelsekällas tidsstämpelegenskap så att den uppfyller behoven i din lösning, men kolumnnamnet i varm och kall lagring är "tidsstämpel". Andra datetime JSON-egenskaper som inte är tidsstämpeln för händelsekällan sparas med "_datetime" i kolumnnamnet, som nämns i regeln ovan.	`"ts": "2020-03-19 14:40:38.318"`	`$event.$ts`	`timestamp`
JSON-egenskapsnamn som innehåller specialtecken. [ \ och ' är undantagna med [' och ']	`"id.wasp": "6A3090FD337DE6B"`	`$event['id.wasp'].String`	`['id.wasp']_string`
Inom [" och "] finns det ytterligare undantag från enkla citattecken och omvänt snedstreck. Ett enda citattecken skrivs som \' och ett omvänt snedstreck skrivs som \\	`"Foo's Law Value": "17.139999389648"`	`$event['Foo\'s Law Value'].Double`	`['Foo\'s Law Value']_double`
Kapslade JSON-objekt plattas ut med en punkt som avgränsare. Kapsling av upp till 10 nivåer stöds.	`"series": {"value" : 316 }`	`$event.series.value.Long`, `$event['series']['value'].Long` eller `$event.series['value'].Long`	`series.value_long`
Matriser av primitiva typer lagras som dynamisk typ	`"values": [154, 149, 147]`	Dynamiska typer kan bara hämtas via GetEvents-API:et	`values_dynamic`
Matriser som innehåller objekt har två beteenden beroende på objektinnehållet: Om antingen TS-ID:t eller tidsstämpelegenskapen (ies) finns i objekten i en matris, kommer matrisen att avregistreras så att den första JSON-nyttolasten genererar flera händelser. På så sätt kan du batcha flera händelser i en JSON-struktur. Alla egenskaper på den översta nivån som är peer-kopplade till matrisen sparas med varje oregistrerat objekt. Om TS-ID:erna och tidsstämpeln inte finns i matrisen sparas de helt som dynamisk typ.	Se exemplen A, B och C nedan
Matriser som innehåller blandade element plattas inte ut.	`"values": ["foo", {"bar" : 149}, 147]`	Dynamiska typer kan bara hämtas via GetEvents-API:et	`values_dynamic`
512 tecken är JSON-egenskapens namngräns. Om namnet överskrider 512 tecken trunkeras det till 512 och '_<'hashCode'>' läggs till. Observera att detta även gäller för egenskapsnamn som har sammanfogats från objekt som planats ut, vilket anger en kapslad objektsökväg.	`"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`

Förstå det dubbla beteendet för matriser

Matriser med objekt lagras antingen helt eller delas upp i flera händelser beroende på hur du har modellerat dina data. På så sätt kan du använda en matris till batchhändelser och undvika upprepade telemetriegenskaper som definieras på rotobjektnivå. Batchbearbetning kan vara fördelaktigt eftersom det resulterar i färre Event Hubs- eller IoT Hub-meddelanden som skickas.

I vissa fall är dock matriser som innehåller objekt bara meningsfulla i samband med andra värden. Att skapa flera händelser skulle göra data meningslösa. För att säkerställa att en matris med objekt lagras som den är som en dynamisk typ följer du riktlinjerna för datamodellering nedan och tar en titt på Exempel C

Så här vet du om min matris med objekt skapar flera händelser

Om en eller flera av time series-ID:t är kapslade i objekt i en matris, eller om tidsstämpelegenskapen för händelsekällan är kapslad, delar inmatningsmotorn ut den för att skapa flera händelser. De egenskapsnamn som du angav för dina TS-ID:er och/eller tidsstämpeln bör följa reglerna för utplattande ovan och anger därför formen på din JSON. Se exemplen nedan och läs guiden om hur du väljer en time series-ID-egenskap.

Exempel A

Tidsserie-ID vid objektroten och tidsstämpeln kapslad
Tidsserie-ID för miljön: "id"
Tidsstämpel för händelsekälla: "values.time"
JSON-nyttolast:

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

Resultat i Parquet-fil:
Konfigurationen och nyttolasten ovan skapar tre kolumner och fyra händelser

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`

Exempel B

Sammansatt tidsserie-ID med en kapslad egenskap
Tidsserie-ID för miljö: "plantId" och "telemetry.tagId"
Tidsstämpel för händelsekälla: "timestamp"
JSON-nyttolast:

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

Resultat i Parquet-fil:
Konfigurationen och nyttolasten ovan skapar fyra kolumner och sex händelser

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

Exempel C

Tidsserie-ID och tidsstämpel finns vid objektroten
Tidsserie-ID för miljön: "id"
Tidsstämpel för händelsekälla: "timestamp"
JSON-nyttolast:

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

Resultat i Parquet-fil:
Konfigurationen och nyttolasten ovan skapar tre kolumner och en händelse

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

Nästa steg

Förstå miljöns dataflödesbegränsningar

Dela via