Appiattimento JSON, escape e gestione delle matrici
Nota
Il servizio Time Series Insights (TSI) non sarà più supportato dopo marzo 2025. Valutare la possibilità di eseguire la migrazione di ambienti Time Series Insights esistenti a soluzioni alternative il prima possibile. Per altre informazioni sulla deprecazione e la migrazione, visitare la documentazione.
L'ambiente Azure Time Series Insights Gen2 creerà dinamicamente le colonne degli archivi ad accesso frequente e sporadico, seguendo un determinato set di convenzioni di denominazione. Quando viene inserito un evento, viene applicato un set di regole ai nomi di payload e proprietà JSON. Questi includono l'escape di 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. Esempi A & B illustrano anche come si è in grado di raggruppare in modo efficiente più serie temporali in una matrice.
Importante
- Esaminare le regole seguenti prima di selezionare una proprietà ID serie temporale e/o il timestamp dell'origine evento propert(ies). Se l'ID TS o il timestamp si trova all'interno di un oggetto annidato o ha uno o più dei caratteri speciali riportati di seguito, è importante assicurarsi che il nome della proprietà specificato corrisponda al nome della colonna dopo l'applicazione delle regole di inserimento. Vedere l'esempio B seguente.
| Regola | JSON di esempio | Sintassi dell'espressione Time Series | Nome colonna proprietà in Parquet |
|---|---|---|---|
| Il tipo di dati Azure Time Series Insights Gen2 viene aggiunto alla fine del nome della colonna come "_<dataType>" | "type": "Accumulated Heat" |
$event.type.String |
type_string |
| La proprietà timestamp dell'origine evento verrà salvata in Azure Time Series Insights Gen2 come "timestamp" nell'archiviazione e il valore archiviato in formato 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. [ \ e ' vengono preceduti da escape usando [' e '] | "id.wasp": "6A3090FD337DE6B" |
$event['id.wasp'].String |
['id.wasp']_string |
| All'interno di [" e "] c'è un'ulteriore escape di virgolette singole e barre rovesciata. 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. L'annidamento di un massimo di 10 livelli è supportato. | "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 |
| Le matrici contenenti oggetti hanno due comportamenti a seconda del contenuto dell'oggetto: se gli ID TS o le proprietà timestamp si trovano all'interno degli oggetti in una matrice, la matrice verrà annullata in modo che il payload JSON iniziale produa più eventi. In questo modo è possibile raggruppare più eventi in una struttura JSON. Tutte le proprietà di primo livello che sono peer della matrice verranno salvate con ogni oggetto senza rollback. Se gli ID TS e il timestamp non si trovano all'interno della matrice, verranno salvati nel suo complesso come tipo dinamico. | Vedere gli esempi A, B e C seguenti | ||
| 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à concatenati dall'oggetto appiattito, che indica 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 |
Informazioni sul doppio comportamento per le matrici
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 hub eventi o hub IoT messaggi 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 sia archiviata così com'è come tipo dinamico, seguire le indicazioni sulla modellazione dei dati di seguito e osservare l'esempio C
Come sapere se la matrice di oggetti produrrà più eventi
Se uno o più id serie temporale propert(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 indicherà quindi la forma del file JSON. Vedere gli esempi seguenti ed esaminare la guida su come selezionare una proprietà ID serie temporale.
Esempio A
ID serie temporale nella radice dell'oggetto e nel timestamp annidato
ID serie temporale dell'ambiente:"id"
Timestamp origine evento:"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
| 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 |
Esempio B
ID serie temporale composita con una proprietà annidata
ID serie temporale dell'ambiente:"plantId" e "telemetry.tagId"
Timestamp 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 temporale dell'ambiente:"id"
Timestamp origine evento:"timestamp"
Payload JSON:
{
"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}] |