Inserire dati di esempio in formato JSON in Azure Esplora datiIngest JSON formatted sample data into Azure Data Explorer

Questo articolo illustra come inserire dati in formato JSON in un database di Esplora dati di Azure.This article shows you how to ingest JSON formatted data into an Azure Data Explorer database. Si inizierà con semplici esempi di JSON non elaborati e mappati, si continuerà a usare JSON con più righe e quindi si affronteranno schemi JSON più complessi contenenti matrici e dizionari.You'll start with simple examples of raw and mapped JSON, continue to multi-lined JSON, and then tackle more complex JSON schemas containing arrays and dictionaries. Gli esempi illustrano in dettaglio il processo di inserimento dei dati in formato JSON usando kusto Query Language (KQL), C# o Python.The examples detail the process of ingesting JSON formatted data using Kusto query language (KQL), C#, or Python. I ingest comandi di controllo del linguaggio di query kusto vengono eseguiti direttamente nell'endpoint del motore.The Kusto query language ingest control commands are executed directly to the engine endpoint. Negli scenari di produzione, l'inserimento viene eseguito al servizio Gestione dati usando le librerie client o le connessioni dati.In production scenarios, ingestion is executed to the Data Management service using client libraries or data connections. Leggi i dati di inserimento usando la libreria Python di azure Esplora dati e Inserisci dati usando Azure Esplora dati .NET standard SDK per una procedura dettagliata sull'inserimento di dati con queste librerie client.Read Ingest data using the Azure Data Explorer Python library and Ingest data using the Azure Data Explorer .NET Standard SDK for a walk-through regarding ingesting data with these client libraries.

PrerequisitiPrerequisites

Un cluster e un database di testA test cluster and database

Formato JSONThe JSON format

Azure Esplora dati supporta due formati di file JSON:Azure Data Explorer supports two JSON file formats:

  • json: Codice JSON separato da righe.json: Line separated JSON. Ogni riga nei dati di input include esattamente un record JSON.Each line in the input data has exactly one JSON record.
  • multijson: JSON con più righe.multijson: Multi-lined JSON. Il parser ignora i separatori di riga e legge un record dalla posizione precedente fino alla fine di un file JSON valido.The parser ignores the line separators and reads a record from the previous position to the end of a valid JSON.

Inserire e mappare i dati in formato JSONIngest and map JSON formatted data

Per l'inserimento di dati in formato JSON è necessario specificare il formato usando la Proprietàdi inserimento.Ingestion of JSON formatted data requires you to specify the format using ingestion property. L'inserimento di dati JSON richiede il mapping, che esegue il mapping di una voce di origine JSON alla relativa colonna di destinazione.Ingestion of JSON data requires mapping, which maps a JSON source entry to its target column. Quando si inseriscono dati, usare la proprietà con la proprietà di inserimento IngestionMapping ingestionMappingReference (per un mapping predefinito) o la relativa IngestionMappings Proprietà.When ingesting data, use the IngestionMapping property with its ingestionMappingReference (for a pre-defined mapping) ingestion property or its IngestionMappings property. In questo articolo verrà usata la ingestionMappingReference proprietà di inserimento, che è predefinita nella tabella usata per l'inserimento.This article will use the ingestionMappingReference ingestion property, which is pre-defined on the table used for ingestion. Negli esempi seguenti si inizierà inserendo i record JSON come dati non elaborati in una tabella a colonna singola.In the examples below, we'll start by ingesting JSON records as raw data to a single column table. Si userà quindi il mapping per inserire ogni proprietà nella relativa colonna mappata.Then we'll use the mapping to ingest each property to its mapped column.

Esempio JSON sempliceSimple JSON example

L'esempio seguente è un semplice JSON, con una struttura flat.The following example is a simple JSON, with a flat structure. I dati hanno informazioni sulla temperatura e sull'umidità, raccolti da diversi dispositivi.The data has temperature and humidity information, collected by several devices. Ogni record è contrassegnato con un ID e un timestamp.Each record is marked with an ID and timestamp.

{
    "timestamp": "2019-05-02 15:23:50.0369439",
    "deviceId": "2945c8aa-f13e-4c48-4473-b81440bb5ca2",
    "messageId": "7f316225-839a-4593-92b5-1812949279b3",
    "temperature": 31.0301639051317,
    "humidity": 62.0791099602725
}

Inserire record JSON non elaboratiIngest raw JSON records

In questo esempio si inseriscono i record JSON come dati non elaborati in una tabella a colonna singola.In this example, you ingest JSON records as raw data to a single column table. La manipolazione dei dati, l'utilizzo di query e i criteri di aggiornamento vengono eseguiti dopo l'inserimento dei dati.The data manipulation, using queries, and update policy is done after the data is ingested.

Usare il linguaggio di query kusto per inserire i dati in un formato JSON non elaborato.Use Kusto query language to ingest data in a raw JSON format.

  1. Accedere a https://dataexplorer.azure.com.Sign in to https://dataexplorer.azure.com.

  2. Selezionare Add cluster (Aggiungi cluster).Select Add cluster.

  3. Nella finestra di dialogo Add cluster (Aggiungi cluster) immettere l'URL del cluster nel modulohttps://<ClusterName>.<Region>.kusto.windows.net/, quindi selezionare Aggiungi.In the Add cluster dialog box, enter your cluster URL in the form https://<ClusterName>.<Region>.kusto.windows.net/, then select Add.

  4. Incollare il comando seguente e selezionare Run ( Esegui ) per creare la tabella.Paste in the following command, and select Run to create the table.

    .create table RawEvents (Event: dynamic)
    

    Questa query crea una tabella con una singola Event colonna di un tipo di dati dinamico .This query creates a table with a single Event column of a dynamic data type.

  5. Creare il mapping JSON.Create the JSON mapping.

    .create table RawEvents ingestion json mapping 'RawEventMapping' '[{"column":"Event","Properties":{"path":"$"}}]'
    

    Questo comando crea un mapping ed esegue il mapping del percorso radice JSON $ alla Event colonna.This command creates a mapping, and maps the JSON root path $ to the Event column.

  6. Inserire i dati nella RawEvents tabella.Ingest data into the RawEvents table.

    .ingest into table RawEvents (h'https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/simple.json?st=2018-08-31T22%3A02%3A25Z&se=2020-09-01T22%3A02%3A00Z&sp=r&sv=2018-03-28&sr=b&sig=LQIbomcKI8Ooz425hWtjeq6d61uEaq21UVX7YrM61N4%3D') with '{"format":json, "ingestionMappingReference":"DiagnosticRawRecordsMapping"}'
    

Inserire record JSON mappatiIngest mapped JSON records

In questo esempio si inseriscono i dati dei record JSON.In this example, you ingest JSON records data. Ogni proprietà JSON è mappata a una singola colonna nella tabella.Each JSON property is mapped to a single column in the table.

  1. Creare una nuova tabella con uno schema simile ai dati di input JSON.Create a new table, with a similar schema to the JSON input data. Questa tabella verrà usata per tutti gli esempi e i comandi di inserimento seguenti.We'll use this table for all the following examples and ingest commands.

    .create table Events (Time: datetime, Device: string, MessageId: string, Temperature: double, Humidity: double)
    
  2. Creare il mapping JSON.Create the JSON mapping.

    .create table Events ingestion json mapping 'FlatEventMapping' '[{"column":"Time","Properties":{"path":"$.timestamp"}},{"column":"Device","Properties":{"path":"$.deviceId"}},{"column":"MessageId","Properties":{"path":"$.messageId"}},{"column":"Temperature","Properties":{"path":"$.temperature"}},{"column":"Humidity","Properties":{"path":"$.humidity"}}]'
    

    In questo mapping, in base a quanto definito dallo schema della tabella, le timestamp voci verranno inserite nella colonna Time come datetime tipi di dati.In this mapping, as defined by the table schema, the timestamp entries will be ingested to the column Time as datetime data types.

  3. Inserire i dati nella Events tabella.Ingest data into the Events table.

    .ingest into table Events (h'https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/simple.json?st=2018-08-31T22%3A02%3A25Z&se=2020-09-01T22%3A02%3A00Z&sp=r&sv=2018-03-28&sr=b&sig=LQIbomcKI8Ooz425hWtjeq6d61uEaq21UVX7YrM61N4%3D') with '{"format":"json", "ingestionMappingReference":"FlatEventMapping"}'
    

    Il file ' simple.json ' contiene alcuni record JSON delimitati da righe.The file 'simple.json' has a few line-separated JSON records. Il formato è json e il mapping usato nel comando di inserimento è l'oggetto FlatEventMapping creato.The format is json, and the mapping used in the ingest command is the FlatEventMapping you created.

Inserire record JSON con più righeIngest multi-lined JSON records

In questo esempio si inseriscono record JSON a più righe.In this example, you ingest multi-lined JSON records. Ogni proprietà JSON è mappata a una singola colonna nella tabella.Each JSON property is mapped to a single column in the table. Il file ' multilined.json ' contiene alcuni record JSON rientrati.The file 'multilined.json' has a few indented JSON records. Il formato multijson indica al motore di leggere i record dalla struttura JSON.The format multijson tells the engine to read records by the JSON structure.

Inserire i dati nella Events tabella.Ingest data into the Events table.

.ingest into table Events (h'https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/multilined.json?st=2018-08-31T22%3A02%3A25Z&se=2020-09-01T22%3A02%3A00Z&sp=r&sv=2018-03-28&sr=b&sig=LQIbomcKI8Ooz425hWtjeq6d61uEaq21UVX7YrM61N4%3D') with '{"format":"multijson", "ingestionMappingReference":"FlatEventMapping"}'

Inserire record JSON contenenti matriciIngest JSON records containing arrays

I tipi di dati matrice sono una raccolta ordinata di valori.Array data types are an ordered collection of values. L'inserimento di una matrice JSON viene eseguito da un criterio di aggiornamento.Ingestion of a JSON array is done by an update policy. Il codice JSON viene inserito così com'è in una tabella intermedia.The JSON is ingested as-is to an intermediate table. Un criterio di aggiornamento esegue una funzione predefinita sulla RawEvents tabella, inserendo nuovamente i risultati nella tabella di destinazione.An update policy runs a pre-defined function on the RawEvents table, reingesting the results to the target table. I dati vengono inseriti con la struttura seguente:We will ingest data with the following structure:

{
    "records": 
    [
        {
            "timestamp": "2019-05-02 15:23:50.0000000",
            "deviceId": "ddbc1bf5-096f-42c0-a771-bc3dca77ac71",
            "messageId": "7f316225-839a-4593-92b5-1812949279b3",
            "temperature": 31.0301639051317,
            "humidity": 62.0791099602725
        },
        {
            "timestamp": "2019-05-02 15:23:51.0000000",
            "deviceId": "ddbc1bf5-096f-42c0-a771-bc3dca77ac71",
            "messageId": "57de2821-7581-40e4-861e-ea3bde102364",
            "temperature": 33.7529423105311,
            "humidity": 75.4787976739364
        }
    ]
}
  1. Creare una update policy funzione che espande la raccolta di records in modo che ogni valore nella raccolta riceva una riga distinta, usando l' mv-expand operatore.Create an update policy function that expands the collection of records so that each value in the collection receives a separate row, using the mv-expand operator. La tabella verrà utilizzata RawEvents come tabella di origine e Events come tabella di destinazione.We'll use table RawEvents as a source table and Events as a target table.

    .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"])
    }
    
  2. Lo schema ricevuto dalla funzione deve corrispondere allo schema della tabella di destinazione.The schema received by the function must match the schema of the target table. Usare getschema operator per esaminare lo schema.Use getschema operator to review the schema.

    EventRecordsExpand() | getschema
    
  3. Aggiungere il criterio di aggiornamento nella tabella di destinazione.Add the update policy to the target table. Questo criterio eseguirà automaticamente la query su tutti i dati appena inseriti nella RawEvents tabella intermedia e inserirà i risultati nella Events tabella.This policy will automatically run the query on any newly ingested data in the RawEvents intermediate table and ingest the results into the Events table. Definire un criterio di conservazione zero per evitare che la tabella intermedia venga mantenuta.Define a zero-retention policy to avoid persisting the intermediate table.

    .alter table Events policy update @'[{"Source": "RawEvents", "Query": "EventRecordsExpand()", "IsEnabled": "True"}]'
    
  4. Inserire i dati nella RawEvents tabella.Ingest data into the RawEvents table.

    .ingest into table RawEvents (h'https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/array.json?st=2018-08-31T22%3A02%3A25Z&se=2020-09-01T22%3A02%3A00Z&sp=r&sv=2018-03-28&sr=b&sig=LQIbomcKI8Ooz425hWtjeq6d61uEaq21UVX7YrM61N4%3D') with '{"format":"multijson", "ingestionMappingReference":"RawEventMapping"}'
    
  5. Esaminare i dati nella Events tabella.Review data in the Events table.

    Events
    

Inserire record JSON contenenti dizionariIngest JSON records containing dictionaries

Il JSON strutturato del dizionario contiene coppie chiave-valore.Dictionary structured JSON contains key-value pairs. I record JSON subiscono il mapping di inserimento usando un'espressione logica in JsonPath .Json records undergo ingestion mapping using logical expression in the JsonPath. È possibile inserire dati con la struttura seguente:You can ingest data with the following structure:

{
    "event": 
    [
        {
            "Key": "timestamp",
            "Value": "2019-05-02 15:23:50.0000000"
        },
        {
            "Key": "deviceId",
            "Value": "ddbc1bf5-096f-42c0-a771-bc3dca77ac71"
        },
        {
            "Key": "messageId",
            "Value": "7f316225-839a-4593-92b5-1812949279b3"
        },
        {
            "Key": "temperature",
            "Value": 31.0301639051317
        },
        {
            "Key": "humidity",
            "Value": 62.0791099602725
        }
    ]
}
  1. Creare un mapping JSON.Create a JSON mapping.

    .create table Events ingestion json mapping 'KeyValueEventMapping' '[{"column":"a","Properties":{"path":"$.event[?(@.Key == \'timestamp\')]"}},{"column":"b","Properties":{"path":"$.event[?(@.Key == \'deviceId\')]"}},{"column":"c","Properties":{"path":"$.event[?(@.Key == \'messageId\')]"}},{"column":"d","Properties":{"path":"$.event[?(@.Key == \'temperature\')]"}},{"column":"Humidity","datatype":"string","Properties":{"path":"$.event[?(@.Key == \'humidity\')]"}}]'
    
  2. Inserire i dati nella Events tabella.Ingest data into the Events table.

    .ingest into table Events (h'https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/dictionary.json?st=2018-08-31T22%3A02%3A25Z&se=2020-09-01T22%3A02%3A00Z&sp=r&sv=2018-03-28&sr=b&sig=LQIbomcKI8Ooz425hWtjeq6d61uEaq21UVX7YrM61N4%3D') with '{"format":"multijson", "ingestionMappingReference":"KeyValueEventMapping"}'
    

Passaggi successiviNext steps