Använda LightIngest till att mata in data i Azure Data Explorer

Artikel
01/23/2024

LightIngest är ett kommandoradsverktyg för ad hoc-datainmatning till Azure Data Explorer. Verktyget kan hämta källdata från en lokal mapp, en Azure Blob Storage-container eller en Amazon S3-bucket.

LightIngest är mest användbart när du vill mata in en stor mängd data, eftersom det inte finns någon tidsbegränsning för inmatningens varaktighet. Det är också användbart när du senare vill fråga efter poster efter den tidpunkt då de skapades och inte när de matades in.

Ett exempel på hur du automatiskt skapar ett LightIngest-kommando finns i mata in historiska data.

Anteckning

Inmatning stöder en maximal filstorlek på 6 GB. Rekommendationen är att mata in filer mellan 100 MB och 1 GB.

Förutsättningar

LightIngest. Det finns två sätt att få LightIngest:
- Ladda ned LightIngest-binärfiler för ditt operativsystem. Se till att packa upp binärfilerna efter nedladdningen.
- Installera LightIngest som ett .NET-verktyg. Den här metoden kräver att du har .NET SDK version 6.0 eller senare installerad på datorn. Kör sedan följande kommando:
```
dotnet tool install -g Microsoft.Azure.Kusto.LightIngest
```

Kör LightIngest

Så här kör du LightIngest:

I kommandotolken anger du LightIngest följt av relevant kommandoradsargument.

Tips

För en lista över kommandoradsargument som stöds anger du LightIngest /help.

Ange ingest- följt av anslutningssträng till Azure Data Explorer-klustret som ska hantera inmatningen. Omslut anslutningssträng med dubbla citattecken och följ specifikationen för Kusto-anslutningssträngar.

Exempel:

LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -pattern:"*.csv.gz" -format:csv -limit:2 -ignoreFirst:true -cr:10.0 -dontWait:true

Prestandarekommendationer

Om du vill hantera inmatningsbelastningen och återställa från tillfälliga fel använder du inmatningsslutpunkten på https://ingest-{yourClusterNameAndRegion}.kusto.windows.net.
För optimala inmatningsprestanda krävs rådatastorleken så att LightIngest kan uppskatta den okomprimerade storleken på lokala filer. LightIngest kanske dock inte kan uppskatta den råa storleken på komprimerade blobar korrekt utan att först ladda ned dem. När du matar in komprimerade blobar anger du rawSizeBytes därför egenskapen för blobmetadata till okomprimerad datastorlek i byte.

Kommandoradsargument

Argument	Typ	Beskrivning	Krävs
	`string`	En Kusto-anslutningssträng som anger kusto-slutpunkten som hanterar inmatningen. Det här värdet ska omges av dubbla citattecken.	✔️
-database, -db	`string`	Måldatabasnamnet för Azure Data Explorer.
-Tabell	`string`	Måltabellnamnet för Azure Data Explorer.	✔️
-sourcePath, -source	`string`	Platsen för källdata, som kan vara antingen en lokal filsökväg, rot-URI:n för en Azure-blobcontainer eller URI:n för en Amazon S3-bucket. Om data lagras i Azure-blobar måste URI:n innehålla lagringskontonyckeln eller signaturen för delad åtkomst (SAS). Om data finns i en S3-bucket måste URI:n innehålla autentiseringsnyckeln. Vi rekommenderar att du omsluter det här värdet med dubbla citattecken. Mer information finns i Anslutningssträngar för lagring. Pass -sourcePath:; personifiera för att lista Azure-lagringsobjekt med användarbehörigheter (auktorisering av användarfråga).	✔️
-managedIdentity, -mi	`string`	Klient-ID för den hanterade identiteten (användartilldelad eller systemtilldelad) som ska användas för anslutning. Använd "system" för systemtilldelad identitet.
-ingestWithManagedIdentity, -imgestmi	`string`	Klient-ID för den hanterade identiteten (användartilldelad eller systemtilldelad) som ska användas för anslutning. Använd "system" för systemtilldelad identitet.
-connectToStorageWithUserAuth, -storageUserAuth	`string`	Autentisera till datakällans lagringstjänst med användarautentiseringsuppgifter. Alternativen för det här värdet är `PROMPT` eller `DEVICE_CODE`.
-connectToStorageLoginUri, -storageLoginUri	`string`	Om `-connectToStorageWithUserAuth` har angetts kan du ange en Microsoft Entra ID inloggnings-URI.
-Prefix	`string`	När källdata som ska matas in finns i bloblagringen delas det här URL-prefixet av alla blobar, exklusive containernamnet. Om data till exempel finns i `MyContainer/Dir1/Dir2`ska prefixet vara `Dir1/Dir2`. Vi rekommenderar att du omsluter det här värdet med dubbla citattecken.
-Mönster	`string`	Mönster med vilket källfiler/blobar väljs. Stöder jokertecken. Till exempel `"*.csv"`. Vi rekommenderar att du omsluter det här värdet med dubbla citattecken.
-zipPattern	`string`	Reguljärt uttryck som ska användas när du väljer vilka filer i ett ZIP-arkiv som ska matas in. Alla andra filer i arkivet ignoreras. Till exempel `"*.csv"`. Vi rekommenderar att du omsluter det här värdet med dubbla citattecken.
-format, -f	`string`	Källdataformat. Måste vara ett av de format som stöds
-ingestionMappingPath, -mappingPath	`string`	En sökväg till en lokal fil för datainmatningskolumnmappning. Se datamappningar.
-ingestionMappingRef, -mappingRef	`string`	Namnet på en datainmatningskolumnmappning som skapades tidigare i tabellen. Se datamappningar.
-creationTimePattern	`string`	När värdet anges används för att extrahera egenskapen CreationTime från filen eller blobsökvägen. Se Så här matar du in data med hjälp av `CreationTime`.
-ignoreFirstRow, -ignoreFirst	`bool`	Om den anges ignoreras den första posten för varje fil/blob. Om källdata till exempel har rubriker.
-Etiketten	`string`	Taggar som ska associeras med inmatade data. Flera förekomster tillåts
-dontWait	`bool`	Om det här är inställt `true`på väntar du inte på att datainmatningen ska slutföras. Användbart vid inmatning av stora mängder filer/blobar.
-compression, -cr	double	Tips om komprimeringsförhållande. Användbart när du matar in komprimerade filer/blobar för att hjälpa Azure Data Explorer utvärdera rådatastorleken. Beräknas som ursprunglig storlek dividerat med komprimerad storlek.
-limit, -l	heltal	Om den anges begränsar du inmatningen till de första N-filerna .
-listOnly, -list	`bool`	Om det anges visas bara de objekt som skulle ha valts för inmatning.
-ingestTimeout	heltal	Tidsgräns i minuter för slutförande av alla inmatningsåtgärder. Standardvärdet är `60`.
-forceSync	`bool`	Om det anges tvingar du synkron inmatning. Standardvärdet är `false`.
-Interaktiva	`bool`	Om värdet `false`är frågar inte efter argumentbekräftelse. För obevakade flöden och icke-interaktiva miljöer. Standardvärdet är `true`.
-dataBatchSize	heltal	Anger den totala storleksgränsen (MB, okomprimerad) för varje inmatningsåtgärd.
-filesInBatch	heltal	Anger gränsen för antal filer/blobar för varje inmatningsåtgärd.
-devTracing, -trace	`string`	Om det anges skrivs diagnostikloggar till en lokal katalog (som standard `RollingLogs` i den aktuella katalogen eller kan ändras genom att ställa in växelvärdet).

Azure Blob-specifika funktioner

Vid användning med Azure-blobar använder LightIngest vissa egenskaper för blobmetadata för att utöka inmatningsprocessen.

Metadataegenskap	Användning
`rawSizeBytes`, `kustoUncompressedSizeBytes`	Om den anges tolkas den som den okomprimerade datastorleken
`kustoCreationTime`, `kustoCreationTimeUtc`	Tolkas som UTC-tidsstämpel. Om den anges används den för att åsidosätta skapandetiden i Kusto. Användbart för återfyllningsscenarier

Användningsexempel

I följande exempel förutsätts att du har installerat LightIngest-binärfiler för operativsystemet. Om du har installerat LightIngest som ett .NET-verktyg ersätter LightIngest du med LightIngest i exemplen.

Mata in historiska data med egenskapen CreationTime

När du läser in historiska data från befintligt system till Azure Data Explorer får alla poster samma inmatningsdatum. Om du vill aktivera partitionering av dina data genom att skapa tid och inte inmatningstid kan du använda -creationTimePattern argumentet. Argumentet -creationTimePattern extraherar CreationTime egenskapen från filen eller blobsökvägen. Mönstret behöver inte återspegla hela objektsökvägen, bara avsnittet som omsluter den tidsstämpel som du vill använda.

Argumentvärdena måste innehålla:

Konstant text omedelbart före tidsstämpelformatet, omgivet av enkla citattecken (prefix)
Tidsstämpelformatet i standardnotationen .NET DateTime
Konstant text omedelbart efter tidsstämpeln (suffixet).

Viktigt

När du anger att skapandetiden ska åsidosättas kontrollerar du att Lookback egenskapen i måltabellens gällande princip för koppling av omfattningar är justerad med värdena i filen eller blobsökvägarna.

Exempel

Ett blobnamn som innehåller datetime enligt följande: historicalvalues19840101.parquet (tidsstämpeln är fyra siffror för året, två siffror för månaden och två siffror för dagen i månaden),

Värdet för -creationTimePattern argumentet är en del av filnamnet: "'historicalvalues'yyyyMMdd'.parquet'"

LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -creationTimePattern:"'historicalvalues'yyyyMMdd'.parquet'"
 -pattern:"*.parquet" -format:parquet -limit:2 -cr:10.0 -dontWait:true

För en blob-URI som refererar till hierarkisk mappstruktur, till exempel https://storageaccount/mycontainer/myfolder/2002/12/01/blobname.extension,

Värdet för -creationTimePattern argumentet är en del av mappstrukturen: "'folder/'yyyy/MM/dd'/blob'"

  LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -creationTimePattern:"'mycontainer/myfolder/'yyyy/MM/dd'/'"
   -pattern:"*.csv.gz" -format:csv -limit:2 -ignoreFirst:true -cr:10.0 -dontWait:true

Mata in blobar med en lagringskontonyckel eller en SAS-token

Mata in 10 blobar under det angivna lagringskontot ACCOUNT, i mappen DIR, under containern CONToch matcha mönstret *.csv.gz
Målet är databasen DB, tabellen TABLEoch inmatningsmappningen MAPPING skapas i förväg på målet
Verktyget väntar tills inmatningsåtgärderna har slutförts
Observera de olika alternativen för att ange måldatabasen och lagringskontonyckeln jämfört med SAS-token

LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}"
  -prefix:"DIR"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -limit:10

LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True;Initial Catalog=DB"
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER}?{SAS token}"
  -prefix:"DIR"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -limit:10

Mata in alla blobar i en container, inte med rubrikrader

Mata in alla blobar under det angivna lagringskontot ACCOUNT, i mappen DIR1/DIR2, under containern CONToch matcha mönstret *.csv.gz
Målet är databasen DB, tabellen TABLEoch inmatningsmappningen MAPPING skapas i förväg på målet
Källblobar innehåller rubrikrad, så verktyget instrueras att släppa den första posten för varje blob
Verktyget publicerar data för inmatning och väntar inte på att inmatningsåtgärderna ska slutföras

LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER}?{SAS token}"
  -prefix:"DIR1/DIR2"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -ignoreFirstRow:true

Mata in alla JSON-filer från en sökväg

Mata in alla filer under sökvägen PATH, som matchar mönstret *.json
Målet är databasen DB, tabellen TABLEoch inmatningsmappningen definieras i en lokal fil MAPPING_FILE_PATH
Verktyget publicerar data för inmatning och väntar inte på att inmatningsåtgärderna ska slutföras

LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"

Mata in filer och skriva diagnostikspårningsfiler

Mata in alla filer under sökvägen PATH, som matchar mönstret *.json
Målet är databasen DB, tabellen TABLEoch inmatningsmappningen definieras i en lokal fil MAPPING_FILE_PATH
Verktyget publicerar data för inmatning och väntar inte på att inmatningsåtgärderna ska slutföras
Diagnostikspårningsfiler skrivs lokalt under mappen LOGS_PATH

LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"
  -trace:"LOGS_PATH"

Dela via