Appiattimento JSON, gestione delle sequenze di escape e degli array

Articolo
01/21/2021

Nota

Il servizio Time Series Insights verrà ritirato il 7 luglio 2024. Valutare la possibilità di eseguire la migrazione di ambienti esistenti a soluzioni alternative il prima possibile. Per altre informazioni sulla deprecazione e la migrazione, vedere la documentazione .

L'ambiente Azure Time Series Insights Gen2 creerà dinamicamente le colonne degli archivi di archiviazione calda e fredda, seguendo specifiche convenzioni di denominazione. Quando viene inserito un evento, viene applicato un set di regole al payload JSON e ai nomi di proprietà. Questi includono l'uso di escape per determinati caratteri speciali e l'appiattimento di oggetti JSON annidati. È importante conoscere queste regole in modo da comprendere come la forma del codice JSON influirà sulla modalità di archiviazione e query degli eventi. Vedere la tabella seguente per l'elenco completo delle regole. Gli esempi A & B dimostrano anche come sia possibile eseguire in batch più serie temporali in una matrice in modo efficiente.

Importante

Esaminare le regole seguenti prima di selezionare una proprietà ID serie temporale e/o l'origine evento timestamp propert(ies). Se l'ID TS o il timestamp si trova all'interno di un oggetto annidato o include uno o più dei caratteri speciali seguenti, è importante assicurarsi che il nome della proprietà specificato corrisponda al nome della colonna dopo che sono state applicate le regole di inserimento con. Vedi l'esempio B di seguito.

Regola	JSON di esempio	Sintassi delle espressioni delle serie temporali	Nome della colonna proprietà in Parquet
Il tipo di dati Azure Time Series Insights Gen2 viene aggiunto alla fine del nome della colonna come "_<tipoDiDato>"	`"type": "Accumulated Heat"`	`$event.type.String`	`type_string`
L'origine evento , proprietà timestamp, verrà salvata in Azure Time Series Insights Gen2 come "timestamp" nell'archiviazione, con il valore archiviato in UTC. È possibile personalizzare la proprietà timestamp dell'origine evento per soddisfare le esigenze della soluzione, ma il nome della colonna nell'archiviazione ad accesso frequente e sporadico è "timestamp". Altre proprietà JSON datetime che non sono il timestamp dell'origine evento verranno salvate con "_datetime" nel nome della colonna, come indicato nella regola precedente.	`"ts": "2020-03-19 14:40:38.318"`	`$event.$ts`	`timestamp`
Nomi di proprietà JSON che includono i caratteri speciali. [ Il carattere \ e ' vengono preceduti dall'escape utilizzando [' e ']	`"id.wasp": "6A3090FD337DE6B"`	`$event['id.wasp'].String`	`['id.wasp']_string`
All'interno di [' e '] c'è un'ulteriore escape di virgolette singole e barre rovesciate. Una virgoletta singola verrà scritta come \' e una barra rovesciata verrà scritta come \\	`"Foo's Law Value": "17.139999389648"`	`$event['Foo\'s Law Value'].Double`	`['Foo\'s Law Value']_double`
Gli oggetti JSON annidati vengono appiattiti con un punto come separatore. È supportato un annidamento fino a 10 livelli.	`"series": {"value" : 316 }`	`$event.series.value.Long`, `$event['series']['value'].Long` o `$event.series['value'].Long`	`series.value_long`
Le matrici di tipi primitivi vengono archiviate come tipo dinamico	`"values": [154, 149, 147]`	I tipi dinamici possono essere recuperati solo tramite l'API GetEvents	`values_dynamic`
Gli array contenenti oggetti presentano due comportamenti a seconda del contenuto dell'oggetto: se gli ID TS o le proprietà timestamp si trovano all'interno degli oggetti in un array, l'array verrà espanso in modo che il carico JSON iniziale produca più eventi. In questo modo è possibile raggruppare più eventi in una struttura JSON. Le proprietà di primo livello che sono collegate all'array verranno salvate con ogni oggetto elaborato singolarmente. Se gli ID TS e il timestamp sono non all'interno della matrice, verrà salvato nel suo complesso come tipo dinamico.	Vedere esempi , Be C di seguito
Le matrici contenenti elementi misti non vengono appiattite.	`"values": ["foo", {"bar" : 149}, 147]`	I tipi dinamici possono essere recuperati solo tramite l'API GetEvents	`values_dynamic`
512 caratteri è il limite del nome della proprietà JSON. Se il nome supera i 512 caratteri, verrà troncato a 512 e '_<'hashCode'>' viene aggiunto. Si noti che questo vale anche per i nomi delle proprietà risultanti dalla concatenazione di un oggetto appiattito, che denota un percorso di oggetto annidato.	`"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`

Comprendere il comportamento duale degli array

Le matrici di oggetti verranno archiviate intere o suddivise in più eventi a seconda della modalità di modellazione dei dati. In questo modo è possibile usare una matrice per inviare in batch gli eventi ed evitare di ripetere le proprietà di telemetria definite a livello di oggetto radice. L'invio in batch può essere vantaggioso perché comporta un minor numero di messaggi dell'hub eventi o dell'hub IoT inviati.

In alcuni casi, tuttavia, le matrici contenenti oggetti sono significative solo nel contesto di altri valori. La creazione di più eventi renderebbe i dati senza significato. Per assicurarsi che una matrice di oggetti venga archiviata as-is come tipo dinamico, seguire le indicazioni sulla modellazione dei dati di seguito e esaminare esempio C

Come sapere se la matrice di oggetti produrrà più eventi

Se uno o più id serie temporale appropriatet(ies) sono annidati all'interno di oggetti in una matrice, o se la proprietà timestamp dell'origine evento è annidata, il motore di inserimento lo dividerà per creare più eventi. I nomi delle proprietà forniti per gli ID TS e/o il timestamp devono seguire le regole di appiattimento precedenti e indicheranno quindi la forma del JSON. Guarda gli esempi seguenti e consulta la guida su come selezionare una proprietà ID serie temporale.

Esempio A

ID serie temporale nella radice dell'oggetto e nel timestamp annidato
Serie temporali dell'ambiente, ID: "id"
timestamp dell'evento di origine :"values.time"
payload JSON :

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

Risultato nel file Parquet:
La configurazione e il payload precedenti produrranno tre colonne e quattro eventi

Marca Temporale	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`

Esempio B

ID serie temporale composita con una proprietà annidata
ID serie temporale ambientale :"plantId" e "telemetry.tagId"
timestamp dell'origine evento :"timestamp"
payload JSON:

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

Risultato nel file Parquet:
La configurazione e il payload precedenti produrranno quattro colonne e sei eventi

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

Esempio C

ID serie temporale e timestamp si trovano nella radice dell'oggetto
ID serie temporali dell'ambiente :"id"
timestamp dell'origine dell'evento: "timestamp"
JSON payload:

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

Risultato nel file Parquet:
La configurazione e il payload precedenti produrranno tre colonne e un evento

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

Passaggi successivi

Comprendere le limitazioni della velocità effettiva dell'ambiente

Condividi tramite