A LightIngest használata az adatok Azure Data Explorerbe történő betöltéséhez
A LightIngest egy parancssori segédprogram az Azure Data Explorer-ba történő alkalmi adatbetöltéshez. A segédprogram lekérheti a forrásadatokat egy helyi mappából, egy Azure Blob Storage-tárolóból vagy egy Amazon S3-gyűjtőből.
A LightIngest akkor hasznos, ha nagy mennyiségű adatot szeretne betöltésre használni, mert nincs időkorlát a betöltési időtartamra. Akkor is hasznos, ha később szeretné lekérdezni a rekordokat a létrehozásuk időpontja szerint, és nem a betöltési időpontnak megfelelően.
Egy LightIngest-parancs automatikus generálására vonatkozó példa: Előzményadatok betöltése.
Megjegyzés
Legfeljebb 6 GB méretű fájl tölthető be. A javaslat a 100 MB és 1 GB közötti fájlok betöltése.
Előfeltételek
- LightIngest. A LightIngest kétféleképpen szerezhető be:
Töltse le a LightIngest bináris fájlokat az operációs rendszerhez. A letöltés után mindenképpen bontsa ki a bináris fájlokat.
Telepítse a LightIngest eszközt .NET-eszközként. Ehhez a módszerhez a .NET SDK 6.0-s vagy újabb verziójának telepítve kell lennie a számítógépen. Ezután futtassa a következő parancsot:
dotnet tool install -g Microsoft.Azure.Kusto.LightIngest
A LightIngest futtatása
A LightIngest futtatása:
A parancssorba írja be a kifejezést
LightIngest
, majd a megfelelő parancssori argumentumot.Tipp
A támogatott parancssori argumentumok listájához írja be a következőt
LightIngest /help
: .Adja meg
ingest-
a kapcsolati karakterlánc a betöltési elemet kezelő Azure Data Explorer-fürthöz. Tegye a kapcsolati karakterlánc dupla idézőjelek közé, és kövesse a Kusto kapcsolati sztringek specifikációját.Például:
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
Teljesítménnyel kapcsolatos javaslatok
A betöltési terhelés legjobb kezeléséhez és az átmeneti hibák utáni helyreállításhoz használja a betöltési végpontot a következő helyen
https://ingest-{yourClusterNameAndRegion}.kusto.windows.net
: .Az optimális betöltési teljesítmény érdekében a nyers adatméretre van szükség, hogy a LightIngest megbecsülhesse a helyi fájlok tömörítetlen méretét. Előfordulhat azonban, hogy a LightIngest nem tudja megfelelően megbecsülni a tömörített blobok nyers méretét anélkül, hogy először letöltené őket. Ezért tömörített blobok betöltésekor állítsa a
rawSizeBytes
blob metaadatainak tulajdonságát tömörítetlen adatméretre bájtban.
Parancssori argumentumok
Argumentum | Típus | Leírás | Kötelező |
---|---|---|---|
string |
Egy Kusto-kapcsolati karakterlánc, amely megadja a betöltést kezelő Kusto-végpontot. Ezt az értéket idézőjelek közé kell tenni. | ✔️ | |
-database, -db | string |
A cél Azure Data Explorer adatbázis neve. | |
-Táblázat | string |
A cél Azure Data Explorer tábla neve. | ✔️ |
-sourcePath, -source | string |
A forrásadatok helye, amely lehet egy helyi fájl elérési útja, egy Azure Blob-tároló gyökér URI-ja vagy egy Amazon S3-gyűjtő URI-ja. Ha az adatokat Azure-blobokban tárolják, az URI-nak tartalmaznia kell a tárfiókkulcsot vagy a közös hozzáférésű jogosultságkódot (SAS). Ha az adatok egy S3-gyűjtőben találhatók, az URI-nak tartalmaznia kell a hitelesítőadat-kulcsot. Javasoljuk, hogy ezt az értéket idézőjelekbe foglalja. További információ: Storage-kapcsolati sztringek. Pass -sourcePath:; megszemélyesítéssel listázhatja a felhasználói engedélyekkel rendelkező Azure Storage-elemeket (felhasználói kérés engedélyezése). | ✔️ |
-managedIdentity, -mi | string |
A csatlakozáshoz használandó felügyelt identitás (felhasználó által hozzárendelt vagy rendszer által hozzárendelt) ügyfél-azonosítója. A rendszer által hozzárendelt identitáshoz használja a "rendszer" kifejezést. | |
-ingestWithManagedIdentity, -imgestmi | string |
A csatlakozáshoz használandó felügyelt identitás (felhasználó által hozzárendelt vagy rendszer által hozzárendelt) ügyfél-azonosítója. A rendszer által hozzárendelt identitáshoz használja a "rendszer" kifejezést. | |
-connectToStorageWithUserAuth, -storageUserAuth | string |
Hitelesítés az adatforrás-tárolási szolgáltatásban felhasználói hitelesítő adatokkal. Ennek az értéknek a beállításai a következők: PROMPT vagy DEVICE_CODE . |
|
-connectToStorageLoginUri, -storageLoginUri | string |
Ha -connectToStorageWithUserAuth be van állítva, megadhat egy Microsoft Entra ID bejelentkezési URI-t. |
|
-Előtag | string |
Ha a betöltendő forrásadatok a blobtárolóban találhatók, ezt az URL-előtagot az összes blob megosztja, kivéve a tároló nevét. Ha például az adatok a fájlban MyContainer/Dir1/Dir2 találhatóak, akkor az előtagnak a következőnek kell lennie Dir1/Dir2 : . Javasoljuk, hogy ezt az értéket idézőjelekbe foglalja. |
|
-Minta | string |
Minta, amely alapján a forrásfájlokat/blobokat a rendszer kiválasztja. Támogatja a helyettesítő karaktereket. Például: "*.csv" . Javasoljuk, hogy ezt az értéket idézőjelekbe foglalja. |
|
-zipPattern | string |
A betöltendő ZIP-archívumban lévő fájlok kiválasztásakor használandó reguláris kifejezés. Az archívumban lévő összes többi fájl figyelmen kívül lesz hagyva. Például: "*.csv" . Javasoljuk, hogy ezt az értéket idézőjelekbe foglalja. |
|
-format, -f | string |
Forrásadat-formátum. A támogatott formátumok egyikének kell lennie | |
-ingestionMappingPath, -mappingPath | string |
Egy helyi fájl elérési útja a betöltési oszlopleképezéshez. Lásd: adatleképezések. | |
-ingestionMappingRef, -mappingRef | string |
A táblában korábban létrehozott betöltési oszlopleképezés neve. Lásd: adatleképezések. | |
-creationTimePattern | string |
Ha be van állítva, a használatával nyeri ki a CreationTime tulajdonságot a fájlból vagy a blob elérési útjából. Lásd : Adatok betöltése a használatával CreationTime . |
|
-ignoreFirstRow, -ignoreFirst | bool |
Ha be van állítva, a rendszer figyelmen kívül hagyja az egyes fájlok/blobok első rekordját. Ha például a forrásadatok fejléceket tartalmaznak. | |
-Tag | string |
A betöltött adatokhoz társítandó címkék. Több előfordulás is engedélyezett | |
-dontWait | bool |
Ha a értékre true van állítva, nem várja meg a betöltés befejezését. Nagy mennyiségű fájl/blob betöltésekor hasznos. |
|
-compression, -cr | double | Tömörítési arányra mutató tipp. Hasznos tömörített fájlok/blobok betöltésekor, hogy az Azure Data Explorer felmérhesse a nyers adatok méretét. Eredeti méretként számítva, tömörített mérettel elosztva. | |
-limit, -l | egész szám | Ha be van állítva, korlátozza a betöltést az első N fájlokra. | |
-listOnly, -list | bool |
Ha be van állítva, csak azokat az elemeket jeleníti meg, amelyek betöltésre lettek kiválasztva. | |
-ingestTimeout | egész szám | Időtúllépés percekben az összes betöltési művelet befejezéséhez. Alapértelmezés szerint a értékre van kapcsolva 60 . |
|
-forceSync | bool |
Ha be van állítva, kényszeríti a szinkron betöltést. Alapértelmezés szerint a értékre van kapcsolva false . |
|
-Interaktív | bool |
Ha a értékre van false állítva, nem kéri az argumentumok megerősítését. Felügyelet nélküli folyamatokhoz és nem interaktív környezetekhez. Az alapértelmezett szint a true . |
|
-dataBatchSize | egész szám | Az egyes betöltési műveletek teljes méretkorlátját (MB, tömörítetlen) állítja be. | |
-filesInBatch | egész szám | Beállítja az egyes betöltési műveletek fájl-/blobszámkorlátját. | |
-devTracing, -trace | string |
Ha be van állítva, a diagnosztikai naplók egy helyi könyvtárba lesznek írva (alapértelmezés szerint RollingLogs az aktuális könyvtárban, vagy módosíthatók a kapcsoló értékének beállításával). |
Azure-blobspecifikus képességek
Az Azure-blobokkal való használat során a LightIngest bizonyos blob-metaadat-tulajdonságokat használ a betöltési folyamat bővítéséhez.
Metadata tulajdonság | Használat |
---|---|
rawSizeBytes , kustoUncompressedSizeBytes |
Ha be van állítva, a rendszer tömörítetlen adatméretként értelmezi |
kustoCreationTime , kustoCreationTimeUtc |
UTC időbélyegként értelmezve. Ha be van állítva, a rendszer felülbírálja a Kusto létrehozási idejét. Hasznos a visszatöltési forgatókönyvekhez |
Használati példák
Az alábbi példák feltételezik, hogy telepítette a LightIngest bináris fájlokat az operációs rendszerhez. Ha a LightIngest eszközt .NET-eszközként telepítette, helyettesítse LightIngest
a LightIngest
példákkal.
Előzményadatok betöltése a CreationTime tulajdonsággal
Ha a meglévő rendszerből betölti az előzményadatokat az Azure Data Explorer, minden rekord ugyanazt a betöltési dátumot kapja. Ha engedélyezni szeretné az adatok particionálását a létrehozási idő és nem a betöltési idő alapján, használhatja az -creationTimePattern
argumentumot. Az -creationTimePattern
argumentum kinyeri a CreationTime
tulajdonságot a fájlból vagy a blob elérési útjából. A mintának nem kell tükröznie a teljes elem elérési útját, csak a használni kívánt időbélyeget tartalmazó szakaszt.
Az argumentumértéknek a következőket kell tartalmaznia:
- Az időbélyeg formátumát közvetlenül megelőző állandó szöveg, egy idézőjelek közé (előtag)
- Az időbélyeg formátuma standard .NET DateTime jelölésben
- Állandó szöveg közvetlenül az időbélyeg (utótag) után.
Fontos
Amikor azt adja meg, hogy a létrehozási időt felül kell bírálni, győződjön meg arról, hogy a Lookback
céltábla hatályos Extents merge szabályzatának tulajdonsága igazodik a fájl- vagy blobútvonalak értékeihez.
Példák
Egy blobnév, amely a következő dátumidőt tartalmazza:
historicalvalues19840101.parquet
(az időbélyeg az év négy számjegye, a hónap két számjegye és a hónap napjának két számjegye),Az argumentum értéke
-creationTimePattern
a fájlnév része: "'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
Hierarchikus mappastruktúrára hivatkozó blob URI-ja esetén, például
https://storageaccount/mycontainer/myfolder/2002/12/01/blobname.extension
:Az argumentum értéke
-creationTimePattern
a mappaszerkezet része: "'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
Blobok betöltése tárfiókkulcs vagy SAS-jogkivonat használatával
- 10 blob betöltése a megadott tárfiók
ACCOUNT
alatt, a mappábanDIR
, a tárolóCONT
alatt, és megfelel a mintának*.csv.gz
- Cél: adatbázis
DB
, táblaTABLE
, és a betöltési leképezésMAPPING
előre létre van kapcsolva a célhelyen - Az eszköz megvárja, amíg a betöltési műveletek befejeződnek
- Figyelje meg a céladatbázis és a tárfiókkulcs és az SAS-jogkivonat megadásának különböző lehetőségeit
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
Az összes blob betöltése egy tárolóban, a fejlécsorokat nem beleértve
- Betölti az összes blobot a megadott tárfiók
ACCOUNT
alatt, a mappábanDIR1/DIR2
, a tárolóbanCONT
, és megfelel a mintának*.csv.gz
- Cél: adatbázis
DB
, táblaTABLE
, és a betöltési leképezésMAPPING
előre létre van kapcsolva a célhelyen - A forrásblobok fejlécsort tartalmaznak, ezért a rendszer arra utasítja az eszközt, hogy ejtse az egyes blobok első rekordját
- Az eszköz feltölti az adatokat a betöltéshez, és nem várja meg, hogy a betöltési műveletek befejeződjenek
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
Az összes JSON-fájl betöltése egy elérési útból
- Az elérési út
PATH
alatt lévő összes fájl betöltése , a mintának megfelelő*.json
- Cél: adatbázis
DB
, táblaTABLE
, és a betöltési leképezés a helyi fájlban van definiálvaMAPPING_FILE_PATH
- Az eszköz feltölti az adatokat a betöltéshez, és nem várja meg, hogy a betöltési műveletek befejeződjenek
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
-database:DB
-table:TABLE
-source:"PATH"
-pattern:*.json
-format:json
-mappingPath:"MAPPING_FILE_PATH"
Fájlok betöltése és diagnosztikai nyomkövetési fájlok írása
- Az elérési út
PATH
alatt lévő összes fájl betöltése , a mintának megfelelő*.json
- Cél: adatbázis
DB
, táblaTABLE
, és a betöltési leképezés a helyi fájlban van definiálvaMAPPING_FILE_PATH
- Az eszköz feltölti az adatokat a betöltéshez, és nem várja meg, hogy a betöltési műveletek befejeződjenek
- A diagnosztikai nyomkövetési fájlok helyileg vannak megírva a mappában
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"