Voorbeeldgegevens in JSON-indeling opnemen in Azure Data Explorer
Artikel
In dit artikel wordt beschreven hoe u met JSON opgemaakte gegevens opneemt in een Azure Data Explorer-database. U begint met eenvoudige voorbeelden van onbewerkte en toegewezen JSON, gaat verder met JSON met meerdere lijnen en pakt vervolgens complexere JSON-schema's met matrices en woordenlijsten aan. De voorbeelden beschrijven het proces van het opnemen van met JSON opgemaakte gegevens met behulp van Kusto-querytaal (KQL), C# of Python.
Notitie
Het wordt afgeraden beheeropdrachten te gebruiken .ingest in productiescenario's. Gebruik in plaats daarvan een gegevensconnector of neem gegevens programmatisch op met behulp van een van de Kusto-clientbibliotheken.
Vereisten
Een Microsoft-account of een Microsoft Entra gebruikersidentiteit. Een Azure-abonnement is niet vereist.
Azure Data Explorer ondersteunt twee JSON-bestandsindelingen:
json: regel gescheiden JSON. Elke regel in de invoergegevens heeft precies één JSON-record. Deze indeling ondersteunt het parseren van opmerkingen en eigenschappen met één aanhalingsteken. Zie JSON-lijnen voor meer informatie.
multijson: Multi-lined JSON. De parser negeert de regelscheidingstekens en leest een record van de vorige positie tot het einde van een geldige JSON.
Notitie
Bij opname met behulp van de wizard Voor opnemen is multijsonde standaardindeling . De indeling kan JSON-records met meerdere regels en matrices van JSON-records verwerken. Wanneer er een parseerfout optreedt, wordt het hele bestand verwijderd. Als u ongeldige JSON-records wilt negeren, selecteert u de optie 'Fouten in gegevensindeling negeren', waarmee de indeling wordt overgeschakeld naar json (JSON-regels).
Als u de JSON Line-indeling () gebruikt,json worden regels die geen geldige JSON-records vertegenwoordigen, overgeslagen tijdens het parseren.
Met JSON opgemaakte gegevens opnemen en toewijzen
Voor opname van gegevens in JSON-indeling moet u de indeling opgeven met behulp van de eigenschap Opname. Voor opname van JSON-gegevens is toewijzing vereist, waardoor een JSON-bronvermelding wordt toegewezen aan de doelkolom. Gebruik bij het opnemen van gegevens de eigenschap met ingestionMappingReference de IngestionMapping bijbehorende opnameeigenschap (voor een vooraf gedefinieerde toewijzing) of de bijbehorende IngestionMappings eigenschap. In dit artikel wordt gebruikgemaakt van de ingestionMappingReference opnameeigenschap, die vooraf is gedefinieerd voor de tabel die wordt gebruikt voor opname. In de onderstaande voorbeelden beginnen we met het opnemen van JSON-records als onbewerkte gegevens in een tabel met één kolom. Vervolgens gebruiken we de toewijzing om elke eigenschap op te nemen in de toegewezen kolom.
Eenvoudig JSON-voorbeeld
Het volgende voorbeeld is een eenvoudige JSON met een platte structuur. De gegevens bevatten informatie over temperatuur en vochtigheid, verzameld door verschillende apparaten. Elke record is gemarkeerd met een id en tijdstempel.
In dit voorbeeld neemt u JSON-records als onbewerkte gegevens op in een tabel met één kolom. Het bewerken van gegevens, het gebruik van query's en het updatebeleid wordt uitgevoerd nadat de gegevens zijn opgenomen.
Voer in het dialoogvenster Cluster toevoegen de URL van uw cluster in de vorm https://<ClusterName>.<Region>.kusto.windows.net/in en selecteer vervolgens Toevoegen.
Plak de volgende opdracht en selecteer Uitvoeren om de tabel te maken.
.create table RawEvents (Event: dynamic)
Met deze query maakt u een tabel met één Event kolom van een dynamisch gegevenstype.
Met deze opdracht maakt u een toewijzing en wijst u het JSON-hoofdpad $ toe aan de Event kolom.
Gegevens opnemen in de RawEvents tabel.
.ingest into table RawEvents ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/simple.json') with '{"format":"json", "ingestionMappingReference":"RawEventMapping"}'
Gebruik C# om gegevens op te nemen in onbewerkte JSON-indeling.
Maak de RawEvents tabel.
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);
Maak een nieuwe tabel met een schema dat vergelijkbaar is met de JSON-invoergegevens. We gebruiken deze tabel voor alle volgende voorbeelden en opnemen van opdrachten.
In deze toewijzing, zoals gedefinieerd door het tabelschema, worden de timestamp vermeldingen opgenomen in de kolom Time als datetime gegevenstypen.
Gegevens opnemen in de Events tabel.
.ingest into table Events ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/simple.json') with '{"format":"json", "ingestionMappingReference":"FlatEventMapping"}'
Het bestand 'simple.json' heeft enkele regel gescheiden JSON-records. De indeling is json, en de toewijzing die wordt gebruikt in de opdracht opnemen is de FlatEventMapping die u hebt gemaakt.
Maak een nieuwe tabel met een schema dat vergelijkbaar is met de JSON-invoergegevens. We gebruiken deze tabel voor alle volgende voorbeelden en opnemen van opdrachten.
In deze toewijzing, zoals gedefinieerd door het tabelschema, worden de timestamp vermeldingen opgenomen in de kolom Time als datetime gegevenstypen.
Gegevens opnemen in de Events tabel.
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);
Het bestand 'simple.json' heeft enkele regel gescheiden JSON-records. De indeling is json, en de toewijzing die wordt gebruikt in de opdracht opnemen is de FlatEventMapping die u hebt gemaakt.
Maak een nieuwe tabel met een schema dat vergelijkbaar is met de JSON-invoergegevens. We gebruiken deze tabel voor alle volgende voorbeelden en opnemen van opdrachten.
Het bestand 'simple.json' heeft een paar regel gescheiden JSON-records. De indeling is json, en de toewijzing die wordt gebruikt in de opdracht opnemen is de FlatEventMapping die u hebt gemaakt.
Multi-lined JSON-records opnemen
In dit voorbeeld neemt u JSON-records met meerdere regels op. Elke JSON-eigenschap wordt toegewezen aan één kolom in de tabel. Het bestand 'multilined.json' heeft enkele ingesprongen JSON-records. De indeling multijson geeft aan dat records moeten worden gelezen door de JSON-structuur.
.ingest into table Events ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/multilined.json') with '{"format":"multijson", "ingestionMappingReference":"FlatEventMapping"}'
Gegevens opnemen in de Events tabel.
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);
Matrixgegevenstypen zijn een geordende verzameling waarden. Opname van een JSON-matrix wordt uitgevoerd door een updatebeleid. De JSON wordt als zodanig opgenomen in een tussenliggende tabel. Een updatebeleid voert een vooraf gedefinieerde functie uit op de RawEvents tabel, waarbij de resultaten opnieuw worden opgenomen in de doeltabel. We nemen gegevens op met de volgende structuur:
Maak een update policy functie waarmee de verzameling van records wordt uitgebreid, zodat elke waarde in de verzameling een afzonderlijke rij ontvangt met behulp van de mv-expand operator. We gebruiken de tabel RawEvents als brontabel en Events als doeltabel.
.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"])
}
Het schema dat door de functie wordt ontvangen, moet overeenkomen met het schema van de doeltabel. Gebruik getschema de operator om het schema te controleren.
EventRecordsExpand() | getschema
Voeg het updatebeleid toe aan de doeltabel. Met dit beleid wordt de query automatisch uitgevoerd op alle nieuw opgenomen gegevens in de RawEvents tussenliggende tabel en worden de resultaten opgenomen in de Events tabel. Definieer een nulretentiebeleid om te voorkomen dat de tussenliggende tabel behouden blijft.
.ingest into table RawEvents ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/array.json') with '{"format":"multijson", "ingestionMappingReference":"RawEventMapping"}'
Controleer de gegevens in de Events tabel.
Events
Maak een updatefunctie die de verzameling van records uitbreidt, zodat elke waarde in de verzameling een afzonderlijke rij ontvangt met behulp van de mv-expand operator. We gebruiken de tabel RawEvents als brontabel en Events als doeltabel.
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);
Notitie
Het schema dat door de functie wordt ontvangen, moet overeenkomen met het schema van de doeltabel.
Voeg het updatebeleid toe aan de doeltabel. Met dit beleid wordt de query automatisch uitgevoerd op alle nieuw opgenomen gegevens in de tussenliggende tabel en worden de RawEvents resultaten ervan opgenomen in de Events tabel. Definieer een nulretentiebeleid om te voorkomen dat de tussenliggende tabel behouden blijft.
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);
Controleer de gegevens in de Events tabel.
Maak een updatefunctie die de verzameling van records uitbreidt, zodat elke waarde in de verzameling een afzonderlijke rij ontvangt met behulp van de mv-expand operator. We gebruiken de tabel RawEvents als brontabel en Events als doeltabel.
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])
Notitie
Het schema dat door de functie wordt ontvangen, moet overeenkomen met het schema van de doeltabel.
Voeg het updatebeleid toe aan de doeltabel. Met dit beleid wordt de query automatisch uitgevoerd op alle nieuw opgenomen gegevens in de tussenliggende tabel en worden de RawEvents resultaten ervan opgenomen in de Events tabel. Definieer een nulretentiebeleid om te voorkomen dat de tussenliggende tabel behouden blijft.