Mata in JSON-formaterade exempeldata i Azure Data Explorer

Artikel
01/10/2024

Den här artikeln visar hur du matar in JSON-formaterade data i en Azure Data Explorer-databas. Du börjar med enkla exempel på rå och mappad JSON, fortsätter till flerkantade JSON och tar sedan itu med mer komplexa JSON-scheman som innehåller matriser och ordlistor. Exemplen beskriver processen för att mata in JSON-formaterade data med hjälp av Kusto-frågespråk (KQL), C#eller Python.

Anteckning

Vi rekommenderar inte att du använder .ingest hanteringskommandon i produktionsscenarier. Använd i stället en dataanslutningsapp eller programmatiskt mata in data med något av Kusto-klientbiblioteken.

Förutsättningar

Ett Microsoft-konto eller en Microsoft Entra användaridentitet. En Azure-prenumeration krävs inte.
Ett Azure Data Explorer-kluster och en databas. Skapa ett kluster och en databas.

JSON-formatet

Azure Data Explorer stöder två JSON-filformat:

json: Radavgränsad JSON. Varje rad i indata har exakt en JSON-post. Det här formatet stöder parsning av kommentarer och egenskaper med enkla citattecken. Mer information finns i JSON-rader.
multijson: Flerfodrad JSON. Parsern ignorerar radavgränsarna och läser en post från den tidigare positionen till slutet av en giltig JSON.

Anteckning

När du matar in med hjälp av inmatningsguiden är multijsonstandardformatet . Formatet kan hantera flerrads-JSON-poster och matriser med JSON-poster. När ett parsningsfel påträffas ignoreras hela filen. Om du vill ignorera ogiltiga JSON-poster väljer du alternativet "Ignorera dataformatfel.", som växlar formatet till json (JSON-rader).

Om du använder JSON Line-formatet (json) hoppas rader som inte representerar giltiga JSON-poster över under parsningen.

Mata in och mappa JSON-formaterade data

Inmatning av JSON-formaterade data kräver att du anger formatet med hjälp av inmatningsegenskapen. Inmatning av JSON-data kräver mappning, som mappar en JSON-källpost till målkolumnen. När du matar in data använder du IngestionMapping egenskapen med dess ingestionMappingReference (för en fördefinierad mappning) inmatningsegenskap eller dess IngestionMappings egenskap. Den här artikeln använder inmatningsegenskapen ingestionMappingReference , som är fördefinierad i tabellen som används för inmatning. I exemplen nedan börjar vi med att mata in JSON-poster som rådata till en tabell med en kolumn. Sedan använder vi mappningen för att mata in varje egenskap till den mappade kolumnen.

Enkelt JSON-exempel

Följande exempel är en enkel JSON med en platt struktur. Data har information om temperatur och luftfuktighet som samlas in av flera enheter. Varje post markeras med ett ID och en tidsstämpel.

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

Mata in råa JSON-poster

I det här exemplet matar du in JSON-poster som rådata till en tabell med en kolumn. Datamanipuleringen, med hjälp av frågor och uppdateringsprincipen görs när data har matats in.

Använd Kusto-frågespråk för att mata in data i ett rå-JSON-format.

Logga in på https://dataexplorer.azure.com.
Välj Lägg till kluster.
I dialogrutan Lägg till kluster anger du kluster-URL:en i formuläret https://<ClusterName>.<Region>.kusto.windows.net/och väljer sedan Lägg till.
Klistra in följande kommando och välj Kör för att skapa tabellen.
```
.create table RawEvents (Event: dynamic)
```
Den här frågan skapar en tabell med en enda Event kolumn av dynamisk datatyp.

Skapa JSON-mappningen.

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

Det här kommandot skapar en mappning och mappar JSON-rotsökvägen $ till Event kolumnen.

Mata in data i tabellen RawEvents .

.ingest into table RawEvents ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/simple.json') with '{"format":"json", "ingestionMappingReference":"RawEventMapping"}'

Använd C# för att mata in data i rå JSON-format.

RawEvents Skapa tabellen.

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);

Skapa JSON-mappningen.

var tableMappingName = "RawEventMapping";
command = CslCommandGenerator.GenerateTableMappingCreateCommand(
    IngestionMappingKind.Json,
    tableName,
    tableMappingName,
    new ColumnMapping[]
    {
        new() { ColumnName = "Events", Properties = new Dictionary<string, string> { { "path", "$" } } }
    }
);

await kustoClient.ExecuteControlCommandAsync(command);

Det här kommandot skapar en mappning och mappar JSON-rotsökvägen $ till Event kolumnen.

Mata in data i tabellen RawEvents .

var ingestUri = "https://ingest-<clusterName>.<region>.kusto.windows.net/";

var ingestConnectionStringBuilder = new KustoConnectionStringBuilder(ingestUri)
{
    FederatedSecurity = true,
    UserID = userId,
    Password = password,
    Authority = tenantId,
    InitialCatalog = databaseName
};
using var ingestClient = KustoIngestFactory.CreateQueuedIngestClient(ingestConnectionStringBuilder);

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);

Anteckning

Data aggregeras enligt batchbearbetningsprincipen, vilket resulterar i en svarstid på några minuter.

Använd Python för att mata in data i rå JSON-format.

RawEvents Skapa tabellen.

KUSTO_URI = "https://<ClusterName>.<Region>.kusto.windows.net/"
KCSB_DATA = KustoConnectionStringBuilder.with_aad_device_authentication(KUSTO_URI, AAD_TENANT_ID)
KUSTO_CLIENT = KustoClient(KCSB_DATA)
TABLE = "RawEvents"

CREATE_TABLE_COMMAND = ".create table " + TABLE + " (Events: dynamic)"
RESPONSE = KUSTO_CLIENT.execute_mgmt(DATABASE, CREATE_TABLE_COMMAND)
dataframe_from_result_table(RESPONSE.primary_results[0])

Skapa JSON-mappningen.

MAPPING = "RawEventMapping"
CREATE_MAPPING_COMMAND = ".create table " + TABLE + " ingestion json mapping '" + MAPPING + """' '[{"column":"Event","path":"$"}]'"""
RESPONSE = KUSTO_CLIENT.execute_mgmt(DATABASE, CREATE_MAPPING_COMMAND)
dataframe_from_result_table(RESPONSE.primary_results[0])

Mata in data i tabellen RawEvents .

INGEST_URI = "https://ingest-<ClusterName>.<Region>.kusto.windows.net/"
KCSB_INGEST = KustoConnectionStringBuilder.with_aad_device_authentication(INGEST_URI, AAD_TENANT_ID)
INGESTION_CLIENT = KustoIngestClient(KCSB_INGEST)
BLOB_PATH = 'https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/simple.json'

INGESTION_PROPERTIES = IngestionProperties(database=DATABASE, table=TABLE, dataFormat=DataFormat.JSON, ingestion_mapping_reference=MAPPING)
BLOB_DESCRIPTOR = BlobDescriptor(BLOB_PATH, FILE_SIZE)
INGESTION_CLIENT.ingest_from_blob(
    BLOB_DESCRIPTOR, ingestion_properties=INGESTION_PROPERTIES)

Anteckning

Data aggregeras enligt batchbearbetningsprincipen, vilket resulterar i en svarstid på några minuter.

Mata in mappade JSON-poster

I det här exemplet matar du in JSON-postdata. Varje JSON-egenskap mappas till en enda kolumn i tabellen.

Skapa en ny tabell med ett liknande schema som JSON-indata. Vi använder den här tabellen för alla följande exempel och inmatningskommandon.
```
.create table Events (Time: datetime, Device: string, MessageId: string, Temperature: double, Humidity: double)
```

Skapa JSON-mappningen.

.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"}}]'

I den här mappningen, som definieras av tabellschemat, matas posterna timestamp in i kolumnen Time som datetime datatyper.

Mata in data i tabellen Events .
```
.ingest into table Events ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/simple.json') with '{"format":"json", "ingestionMappingReference":"FlatEventMapping"}'
```
Filen "simple.json" har några radavgränsade JSON-poster. Formatet är json, och mappningen som används i inmatningskommandot är den FlatEventMapping du skapade.

Skapa en ny tabell med ett liknande schema som JSON-indata. Vi använder den här tabellen för alla följande exempel och inmatningskommandon.

var tableName = "Events";
var command = CslCommandGenerator.GenerateTableCreateCommand(
   tableName,
   new[]
   {
       Tuple.Create("Time", "System.DateTime"),
       Tuple.Create("Device", "System.String"),
       Tuple.Create("MessageId", "System.String"),
       Tuple.Create("Temperature", "System.Double"),
       Tuple.Create("Humidity", "System.Double")
   }
);
await kustoClient.ExecuteControlCommandAsync(command);

Skapa JSON-mappningen.

var tableMappingName = "FlatEventMapping";
command = CslCommandGenerator.GenerateTableMappingCreateCommand(
    IngestionMappingKind.Json,
    tableName,
    tableMappingName,
    new ColumnMapping[]
    {
        new() { ColumnName = "Time", Properties = new Dictionary<string, string> { { MappingConsts.Path, "$.timestamp" } } },
        new() { ColumnName = "Device", Properties = new Dictionary<string, string> { { MappingConsts.Path, "$.deviceId" } } },
        new() { ColumnName = "MessageId", Properties = new Dictionary<string, string> { { MappingConsts.Path, "$.messageId" } } },
        new() { ColumnName = "Temperature", Properties = new Dictionary<string, string> { { MappingConsts.Path, "$.temperature" } } },
        new() { ColumnName = "Humidity", Properties = new Dictionary<string, string> { { MappingConsts.Path, "$.humidity" } } }
    }
);
await kustoClient.ExecuteControlCommandAsync(command);

I den här mappningen, som definieras av tabellschemat, matas posterna timestamp in i kolumnen Time som datetime datatyper.

Mata in data i tabellen Events .

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);

Filen "simple.json" har några radavgränsade JSON-poster. Formatet är json, och mappningen som används i inmatningskommandot är den FlatEventMapping du skapade.

Skapa en ny tabell med ett liknande schema som JSON-indata. Vi använder den här tabellen för alla följande exempel och inmatningskommandon.

TABLE = "Events"
CREATE_TABLE_COMMAND = ".create table " + TABLE + " (Time: datetime, Device: string, MessageId: string, Temperature: double, Humidity: double)"
RESPONSE = KUSTO_CLIENT.execute_mgmt(DATABASE, CREATE_TABLE_COMMAND)
dataframe_from_result_table(RESPONSE.primary_results[0])

Skapa JSON-mappningen.

MAPPING = "FlatEventMapping"
CREATE_MAPPING_COMMAND = ".create table Events ingestion json mapping '" + MAPPING + """' '[{"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"}}]'"""
RESPONSE = KUSTO_CLIENT.execute_mgmt(DATABASE, CREATE_MAPPING_COMMAND)
dataframe_from_result_table(RESPONSE.primary_results[0])

Mata in data i tabellen Events .

BLOB_PATH = 'https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/simple.json'

INGESTION_PROPERTIES = IngestionProperties(database=DATABASE, table=TABLE, dataFormat=DataFormat.JSON, ingestion_mapping_reference=MAPPING)
BLOB_DESCRIPTOR = BlobDescriptor(BLOB_PATH, FILE_SIZE)
INGESTION_CLIENT.ingest_from_blob(
    BLOB_DESCRIPTOR, ingestion_properties=INGESTION_PROPERTIES)

Filen "simple.json" har några radavgränsade JSON-poster. Formatet är json, och mappningen som används i inmatningskommandot är den FlatEventMapping du skapade.

Mata in flerkantade JSON-poster

I det här exemplet matar du in flerfodrade JSON-poster. Varje JSON-egenskap mappas till en enda kolumn i tabellen. Filen "multilined.json" har några indragna JSON-poster. Formatet multijson anger att poster ska läsas av JSON-strukturen.

Mata in data i tabellen Events .

.ingest into table Events ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/multilined.json') with '{"format":"multijson", "ingestionMappingReference":"FlatEventMapping"}'

Mata in data i tabellen Events .

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);

Mata in data i tabellen Events .

MAPPING = "FlatEventMapping"
BLOB_PATH = 'https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/multilined.json'
INGESTION_PROPERTIES = IngestionProperties(database=DATABASE, table=TABLE, dataFormat=DataFormat.MULTIJSON, ingestion_mapping_reference=MAPPING)
BLOB_DESCRIPTOR = BlobDescriptor(BLOB_PATH, FILE_SIZE)
INGESTION_CLIENT.ingest_from_blob(
    BLOB_DESCRIPTOR, ingestion_properties=INGESTION_PROPERTIES)

Mata in JSON-poster som innehåller matriser

Matrisdatatyper är en ordnad samling värden. Inmatningen av en JSON-matris görs av en uppdateringsprincip. JSON matas in som den är till en mellanliggande tabell. En uppdateringsprincip kör en fördefinierad funktion i RawEvents tabellen och återesterar resultatet till måltabellen. Vi matar in data med följande struktur:

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

Skapa en update policy funktion som expanderar samlingen av records så att varje värde i samlingen får en separat rad med operatorn mv-expand . Vi använder tabellen RawEvents som en källtabell och Events som en måltabell.

.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"])
}

Schemat som tas emot av funktionen måste matcha schemat för måltabellen. Använd getschema operatorn för att granska schemat.
```
EventRecordsExpand() | getschema
```
Lägg till uppdateringsprincipen i måltabellen. Den här principen kör automatiskt frågan på nyligen inmatade data i den RawEvents mellanliggande tabellen och matar in resultatet i Events tabellen. Definiera en nollkvarhållningsprincip för att undvika att den mellanliggande tabellen bevaras.
```
.alter table Events policy update @'[{"Source": "RawEvents", "Query": "EventRecordsExpand()", "IsEnabled": "True"}]'
```

Mata in data i tabellen RawEvents .

.ingest into table RawEvents ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/array.json') with '{"format":"multijson", "ingestionMappingReference":"RawEventMapping"}'

Granska data i tabellen Events .
```
Events
```

Skapa en uppdateringsfunktion som expanderar samlingen av records så att varje värde i samlingen tar emot en separat rad med operatorn mv-expand . Vi använder tabellen RawEvents som en källtabell och Events som en måltabell.

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);

Anteckning

Schemat som tas emot av funktionen måste matcha schemat för måltabellen.

Lägg till uppdateringsprincipen i måltabellen. Den här principen kör automatiskt frågan på nyligen inmatade data i den RawEvents mellanliggande tabellen och matar in dess resultat i Events tabellen. Definiera en nollkvarhållningsprincip för att undvika att den mellanliggande tabellen bevaras.
```
command = ".alter table Events policy update @'[{'Source': 'RawEvents', 'Query': 'EventRecordsExpand()', 'IsEnabled': 'True'}]";
await kustoClient.ExecuteControlCommandAsync(command);
```

Mata in data i tabellen RawEvents .

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);

Granska data i tabellen Events .

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])

Anteckning

Schemat som tas emot av funktionen måste matcha schemat för måltabellen.

Lägg till uppdateringsprincipen i måltabellen. Den här principen kör automatiskt frågan på nyligen inmatade data i den RawEvents mellanliggande tabellen och matar in dess resultat i Events tabellen. Definiera en nollkvarhållningsprincip för att undvika att den mellanliggande tabellen bevaras.
```
CREATE_UPDATE_POLICY_COMMAND =
    """.alter table Events policy update @'[{'Source': 'RawEvents', 'Query': 'EventRecordsExpand()', 'IsEnabled': 'True'}]"""
RESPONSE = KUSTO_CLIENT.execute_mgmt(DATABASE, CREATE_UPDATE_POLICY_COMMAND)
dataframe_from_result_table(RESPONSE.primary_results[0])
```

Mata in data i tabellen RawEvents .

TABLE = "RawEvents"
MAPPING = "RawEventMapping"
BLOB_PATH = 'https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/array.json'
INGESTION_PROPERTIES = IngestionProperties(database=DATABASE, table=TABLE, dataFormat=DataFormat.MULTIJSON, ingestion_mapping_reference=MAPPING)
BLOB_DESCRIPTOR = BlobDescriptor(BLOB_PATH, FILE_SIZE)
INGESTION_CLIENT.ingest_from_blob(
    BLOB_DESCRIPTOR, ingestion_properties=INGESTION_PROPERTIES)

Granska data i tabellen Events .

Dela via

Mata in JSON-formaterade exempeldata i Azure Data Explorer

Förutsättningar

JSON-formatet

Mata in och mappa JSON-formaterade data

Enkelt JSON-exempel

Mata in råa JSON-poster

Mata in mappade JSON-poster

Mata in flerkantade JSON-poster

Mata in JSON-poster som innehåller matriser

Feedback

Ytterligare resurser

Dela via

Mata in JSON-formaterade exempeldata i Azure Data Explorer

Förutsättningar

JSON-formatet

Mata in och mappa JSON-formaterade data

Enkelt JSON-exempel

Mata in råa JSON-poster

Mata in mappade JSON-poster

Mata in flerkantade JSON-poster

Mata in JSON-poster som innehåller matriser

Relaterat innehåll

Feedback

Ytterligare resurser