A LightIngest használata az adatok Azure Data Explorerbe történő betöltéséhez

  • Cikk

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

A LightIngest futtatása

A LightIngest futtatása:

  1. 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: .

  2. 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/Dir2talá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 truevan á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 ACCOUNTalatt, a mappában DIR, a tároló CONTalatt, és megfelel a mintának *.csv.gz
  • Cél: adatbázis DB, tábla TABLE, és a betöltési leképezés MAPPING 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 ACCOUNTalatt, a mappában DIR1/DIR2, a tárolóban CONT, és megfelel a mintának *.csv.gz
  • Cél: adatbázis DB, tábla TABLE, és a betöltési leképezés MAPPING 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 PATHalatt lévő összes fájl betöltése , a mintának megfelelő *.json
  • Cél: adatbázis DB, tábla TABLE, és a betöltési leképezés a helyi fájlban van definiálva MAPPING_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 PATHalatt lévő összes fájl betöltése , a mintának megfelelő *.json
  • Cél: adatbázis DB, tábla TABLE, és a betöltési leképezés a helyi fájlban van definiálva MAPPING_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"