Dela via


JSON-utplattning, undantag och matrishantering

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