Inserire dati di esempio formattati JSON in Azure Esplora dati
Articolo
Questo articolo illustra come inserire dati formattati JSON in un database di Esplora dati di Azure. Si inizierà con semplici esempi di JSON non elaborati e mappati, continuare a JSON con più righe e quindi affrontare schemi JSON più complessi contenenti matrici e dizionari. Gli esempi illustrano in dettaglio il processo di inserimento di dati formattati JSON usando Linguaggio di query Kusto (KQL), C#o Python.
Nota
Non è consigliabile usare .ingest i comandi di gestione negli scenari di produzione. Usare invece un connettore dati o inserire dati a livello di codice usando una delle librerie client Kusto.
Prerequisiti
Un account Microsoft o un'identità utente di Microsoft Entra. Non è necessaria una sottoscrizione di Azure.
Azure Esplora dati supporta due formati di file JSON:
json: JSON separato dalla riga. Ogni riga nei dati di input ha esattamente un record JSON. Questo formato supporta l'analisi dei commenti e delle proprietà con virgolette singole. Per altre informazioni, vedere Linee JSON.
multijson: JSON con più righe. Il parser ignora i separatori di riga e legge un record dalla posizione precedente alla fine di un codice JSON valido.
Nota
Quando si inserisce usando la procedura guidata di inserimento, il formato predefinito è multijson. Il formato può gestire record JSON multilinea e matrici di record JSON. Quando viene rilevato un errore di analisi, l'intero file viene rimosso. Per ignorare i record JSON non validi, selezionare l'opzione "Ignora errori di formato dati".", che cambierà il formato su json (righe JSON).
Se si usa il formato riga JSON (json), le righe che non rappresentano un record JSON valido vengono ignorate durante l'analisi.
Inserire e mappare i dati formattati JSON
L'inserimento di dati formattati JSON richiede di specificare il formato usando la proprietà di inserimento. L'inserimento di dati JSON richiede il mapping, che esegue il mapping di una voce di origine JSON alla colonna di destinazione. Quando si inseriscono dati, usare la IngestionMapping proprietà con la relativa ingestionMappingReference proprietà (per un mapping pre-definito) o la relativa IngestionMappings proprietà. Questo articolo userà la ingestionMappingReference proprietà di inserimento, predefinita nella tabella usata per l'inserimento. Negli esempi seguenti si inizierà inserendo record JSON come dati non elaborati in una singola tabella di colonne. Verrà quindi usato il mapping per inserire ogni proprietà nella colonna mappata.
Esempio JSON semplice
L'esempio seguente è un codice JSON semplice, con una struttura flat. I dati hanno informazioni sulla temperatura e sull'umidità, raccolte da diversi dispositivi. Ogni record viene contrassegnato con un ID e un timestamp.
In questo esempio vengono inseriti record JSON come dati non elaborati in una singola tabella di colonna. La manipolazione dei dati, l'uso di query e i criteri di aggiornamento vengono eseguiti dopo l'inserimento dei dati.
Nella finestra di dialogo Add cluster (Aggiungi cluster) immettere l'URL del cluster nel modulohttps://<ClusterName>.<Region>.kusto.windows.net/, quindi selezionare Aggiungi.
Incollare nel comando seguente e selezionare Esegui per creare la tabella.
.create table RawEvents (Event: dynamic)
Questa query crea una tabella con una singola Event colonna di un tipo di dati dinamico .
Questo comando crea un mapping e esegue il mapping del percorso $ radice JSON alla Event colonna.
Inserire dati nella RawEvents tabella.
.ingest into table RawEvents ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/simple.json') with '{"format":"json", "ingestionMappingReference":"RawEventMapping"}'
Usare C# per inserire dati in formato JSON non elaborato.
Creare la RawEvents tabella.
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net/";
var connectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
{
FederatedSecurity = true,
UserID = userId,
Password = password,
Authority = tenantId,
InitialCatalog = databaseName
};
using var kustoClient = KustoClientFactory.CreateCslAdminProvider(connectionStringBuilder);
var tableName = "RawEvents";
var command = CslCommandGenerator.GenerateTableCreateCommand(
tableName,
new[] { Tuple.Create("Events", "System.Object") }
);
await kustoClient.ExecuteControlCommandAsync(command);
Creare una nuova tabella con uno schema simile ai dati di input JSON. Questa tabella verrà usata per tutti gli esempi e i comandi di inserimento seguenti.
In questo mapping, come definito dallo schema della tabella, le timestamp voci verranno inserite nella colonna Time come datetime tipi di dati.
Inserire dati nella Events tabella.
.ingest into table Events ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/simple.json') with '{"format":"json", "ingestionMappingReference":"FlatEventMapping"}'
Il file 'simple.json' ha alcuni record JSON separati da righe. Il formato è jsone il mapping usato nel comando di inserimento è quello FlatEventMapping creato.
Creare una nuova tabella con uno schema simile ai dati di input JSON. Questa tabella verrà usata per tutti gli esempi e i comandi di inserimento seguenti.
In questo mapping, come definito dallo schema della tabella, le timestamp voci verranno inserite nella colonna Time come datetime tipi di dati.
Inserire dati nella Events tabella.
var blobPath = "https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/simple.json";
var properties = new KustoQueuedIngestionProperties(databaseName, tableName)
{
Format = DataSourceFormat.json,
IngestionMapping = new IngestionMapping { IngestionMappingReference = tableMappingName }
};
await ingestClient.IngestFromStorageAsync(blobPath, properties).ConfigureAwait(false);
Il file 'simple.json' ha alcuni record JSON separati da righe. Il formato è jsone il mapping usato nel comando di inserimento è quello FlatEventMapping creato.
Creare una nuova tabella con uno schema simile ai dati di input JSON. Questa tabella verrà usata per tutti gli esempi e i comandi di inserimento seguenti.
Il file 'simple.json' ha alcuni record JSON separati da righe. Il formato è jsone il mapping usato nel comando di inserimento è quello FlatEventMapping creato.
Inserire record JSON con più righe
In questo esempio si inseriscono record JSON con più righe. Ogni proprietà JSON viene mappata a una singola colonna nella tabella. Il file 'multilined.json' ha alcuni record JSON rientro. Il formato multijson indica di leggere i record dalla struttura JSON.
.ingest into table Events ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/multilined.json') with '{"format":"multijson", "ingestionMappingReference":"FlatEventMapping"}'
Inserire i dati nella Events tabella.
var tableMappingName = "FlatEventMapping";
var blobPath = "https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/multilined.json";
var properties = new KustoQueuedIngestionProperties(databaseName, tableName)
{
Format = DataSourceFormat.multijson,
IngestionMapping = new IngestionMapping { IngestionMappingReference = tableMappingName }
};
await ingestClient.IngestFromStorageAsync(blobPath, properties).ConfigureAwait(false);
I tipi di dati matrice sono una raccolta ordinata di valori. L'inserimento di una matrice JSON viene eseguito da un criterio di aggiornamento. Il codice JSON viene inserito così come è in una tabella intermedia. Un criterio di aggiornamento esegue una funzione predefinita nella RawEvents tabella, reimpostando i risultati nella tabella di destinazione. I dati verranno inseriti con la struttura seguente:
Creare una update policy funzione che espande la raccolta di records in modo che ogni valore nella raccolta riceva una riga separata, usando l'operatore mv-expand . La tabella RawEvents verrà usata come tabella di origine e Events come tabella di destinazione.
.create function EventRecordsExpand() {
RawEvents
| mv-expand records = Event.records
| project
Time = todatetime(records["timestamp"]),
Device = tostring(records["deviceId"]),
MessageId = tostring(records["messageId"]),
Temperature = todouble(records["temperature"]),
Humidity = todouble(records["humidity"])
}
Lo schema ricevuto dalla funzione deve corrispondere allo schema della tabella di destinazione. Usare l'operatore getschema per esaminare lo schema.
EventRecordsExpand() | getschema
Aggiungere il criterio di aggiornamento nella tabella di destinazione. Questo criterio eseguirà automaticamente la query su tutti i dati appena inseriti nella RawEvents tabella intermedia e inserisce i risultati nella Events tabella. Definire criteri di conservazione zero per evitare di rendere persistente la tabella intermedia.
.ingest into table RawEvents ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/array.json') with '{"format":"multijson", "ingestionMappingReference":"RawEventMapping"}'
Esaminare i dati nella Events tabella.
Events
Creare una funzione di aggiornamento che espande la raccolta di records in modo che ogni valore nella raccolta riceva una riga separata, usando l'operatore mv-expand . La tabella RawEvents verrà usata come tabella di origine e Events come tabella di destinazione.
var command = CslCommandGenerator.GenerateCreateFunctionCommand(
"EventRecordsExpand",
"UpdateFunctions",
string.Empty,
null,
@"RawEvents
| mv-expand records = Event
| project
Time = todatetime(records['timestamp']),
Device = tostring(records['deviceId']),
MessageId = tostring(records['messageId']),
Temperature = todouble(records['temperature']),
Humidity = todouble(records['humidity'])",
ifNotExists: false
);
await kustoClient.ExecuteControlCommandAsync(command);
Nota
Lo schema ricevuto dalla funzione deve corrispondere allo schema della tabella di destinazione.
Aggiungere il criterio di aggiornamento nella tabella di destinazione. Questo criterio eseguirà automaticamente la query su tutti i dati appena inseriti nella RawEvents tabella intermedia e inserisce i risultati nella Events tabella. Definire criteri di conservazione zero per evitare di rendere persistente la tabella intermedia.
var blobPath = "https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/array.json";
var tableName = "RawEvents";
var tableMappingName = "RawEventMapping";
var properties = new KustoQueuedIngestionProperties(databaseName, tableName)
{
Format = DataSourceFormat.multijson,
IngestionMapping = new IngestionMapping { IngestionMappingReference = tableMappingName }
};
await ingestClient.IngestFromStorageAsync(blobPath, properties);
Esaminare i dati nella Events tabella.
Creare una funzione di aggiornamento che espande la raccolta di records in modo che ogni valore nella raccolta riceva una riga separata, usando l'operatore mv-expand . La tabella RawEvents verrà usata come tabella di origine e Events come tabella di destinazione.
CREATE_FUNCTION_COMMAND =
'''.create function EventRecordsExpand() {
RawEvents
| mv-expand records = Event
| project
Time = todatetime(records["timestamp"]),
Device = tostring(records["deviceId"]),
MessageId = tostring(records["messageId"]),
Temperature = todouble(records["temperature"]),
Humidity = todouble(records["humidity"])
}'''
RESPONSE = KUSTO_CLIENT.execute_mgmt(DATABASE, CREATE_FUNCTION_COMMAND)
dataframe_from_result_table(RESPONSE.primary_results[0])
Nota
Lo schema ricevuto dalla funzione deve corrispondere allo schema della tabella di destinazione.
Aggiungere il criterio di aggiornamento nella tabella di destinazione. Questo criterio eseguirà automaticamente la query su tutti i dati appena inseriti nella RawEvents tabella intermedia e inserisce i risultati nella Events tabella. Definire criteri di conservazione zero per evitare di rendere persistente la tabella intermedia.