Adatok betöltése az Azure Data Explorerbe a LightIngest használatával

A LightIngest egy parancssori segédprogram az Azure Data Explorerbe 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.

A LightIngest-parancsok automatikus generálásának módjáról az előzményadatok betöltése című témakörben talál példát.

Megjegyzés:

A betöltés legfeljebb 6 GB fájlméretet támogat. A javaslat a fájlok 100 MB és 1 GB közötti betöltése.

Előfeltételek

Megjegyzés:

Fontolja meg a várólistán lévő betöltési parancsok használatát, mivel ezek nem igényelnek szoftvertelepítést.

LightIngest futtatása

A LightIngest futtatása:

  1. A parancssorba írja be a LightIngest követve a megfelelő parancssori argumentumot.

    Jótanács

    A támogatott parancssori argumentumok listájához írja be a következőt LightIngest /help: .

  2. Adja meg a ingest- után az adatbevitelt kezelő Azure Data Explorer-fürt számára a kapcsolati sztringet. Csatolja a kapcsolati sztringet 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ése és az átmeneti hibákból való helyreállítás érdekében 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 LightIngestnek szüksége van a nyers adatméretre, hogy 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ölti őket. Ezért a tömörített blobok betöltésekor állítsa a rawSizeBytes blob metaadatainak tulajdonságát tömörítetlen adatméretre bájtokban.

Parancssori paraméterek

Argument Típus Description Kötelező
string Egy Kusto karakterlánc, amely megadja az adat bevitelét kezelő Kusto-végpontot. Ezt az értéket dupla idézőjelekbe foglalja. ✔️
-adatbázis, -db string A cél Azure Data Explorer-adatbázis neve.
-asztal 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ók kulcsát 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ő kulcsot. Ezt az értéket dupla idézőjelekbe foglalja. További információ: Tárhely összekötési karakterláncok. Pass -sourcePath:; megszemélyesítés az Azure Storage felhasználói engedélyekkel rendelkező elemeinek listázására (felhasználói kérés engedélyezése). ✔️
-managedIdentity, -mi string A csatlakozáshoz használni kívánt felügyelt identitás ügyfélazonosítója (felhasználó által hozzárendelt vagy rendszer által hozzárendelt). A rendszer által hozzárendelt identitáshoz használja a "system" kifejezést.
-azCli bool Ha be van állítva, az Azure CLI használatával hitelesítheti magát a Kusto szolgáltatásban. Az Azure CLI-t telepíteni és bejelentkezni kell.
-ingestWithManagedIdentity, -ingestmi string A felügyelt identitás ügyfélazonosítója (felhasználó által hozzárendelt vagy rendszer által hozzárendelt), amely a Kusto szolgáltatásban van telepítve a tárolóból történő letöltéshez. A rendszer által hozzárendelt identitáshoz használja a "system" kifejezést.
-connectToStorageWithManagedIdentity, -storageMi string Az ügyféloldalon telepített felügyelt identitás (felhasználó által hozzárendelt vagy rendszer által hozzárendelt) ügyfélazonosítója a tárterületről történő listázáshoz.
-connectToStorageWithUserAuth, -storageUserAuth string Hitelesítés az adatforrás-tároló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őképző string Ha a betöltendő forrásadatok a blobtárolóban találhatók, ezt az URL-előtagot az összes blob megosztja, a tároló nevének kivételével.
Ha például az adatok benne MyContainer/Dir1/Dir2van, akkor az előtagnak kell lennie Dir1/Dir2. Ezt az értéket dupla idézőjelekbe foglalja.
-minta string Minta, amely alapján a forrásfájlokat és a blobokat választja ki. Támogatja a helyettesítő karaktereket. Például: "*.csv". Ezt az értéket dupla idézőjelekbe foglalja.
-zipPattern string A ZIP-archívumban betöltendő fájlok kiválasztásakor használandó reguláris kifejezés. Az archívum összes többi fájlja figyelmen kívül lesz hagyva. Például: "*.csv". Ezt az értéket dupla 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 az adatleképezéseket.
-ingestionMappingRef, -mappingRef string A táblában korábban létrehozott betöltési oszlopleképezés neve. Lásd az adatleképezéseket.
-creationTimePattern string Ha be van állítva, kinyeri a CreationTime tulajdonságot a fájl vagy a blob elérési útvonalából. Lásd Adatok betöltése az CreationTime használatával.
-ignoreFirstRow, -ignoreFirst bool Ha be van állítva, a rendszer figyelmen kívül hagyja az egyes fájlok vagy blobok első rekordját. Ha például a forrásadatok fejléceket használnak.
-címke string A betöltött adatokhoz társítandó címkék. Több előfordulás is engedélyezett
-dontWait bool Ha a true be van állítva, nem várja meg a betöltési befejezést. Nagy mennyiségű fájlok és blobok feldolgozásakor hasznos.
-tömörítés, -cr dupla Tömörítési arányra mutató tipp. A tömörített fájlok és blobok betöltésekor hasznos, hogy segítsen az Azure Data Explorernek felmérni a nyers adatok méretét. Eredeti méretként számítva, tömörített mérettel osztva.
-limit (korlátozás), -l egész szám Ha be van állítva, az első N fájlra korlátozza az adatbevitelt.
-csakLista, -lista bool Ha be van állítva, csak a betöltéshez kiválasztott elemek jelennek meg.
-ingestTimeout egész szám Az összes betöltési művelet befejezéséhez szükséges időtúllépés, percekben mérve. Alapértelmezett érték: 60.
-forceSync bool Ha be van állítva, kényszeríti a szinkron beolvasást. Alapértelmezett érték: false.
-interaktív bool Ha be van állítva, falsenem kéri az argumentumok megerősítését. Felügyelet nélküli folyamatokhoz és nem interaktív környezetekhez. Az alapértelmezett érték 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- és blobszámkorlátját.
-devTracing, -trace string Ha be van állítva, a diagnosztikai naplók 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

Ha a LightIngestet azure-blobokkal használja, az bizonyos blob-metaadat-tulajdonságokat használ a betöltési folyamat javítására.

Metaadat-tulajdonság Usage
rawSizeBytes, kustoUncompressedSizeBytes Ha be van állítva, a LightIngest ezeket a tulajdonságokat tömörítetlen adatméretként értelmezi
kustoCreationTime, kustoCreationTimeUtc A LightIngest ezeket a tulajdonságokat UTC időbélyegként értelmezi. Ha be van állítva, ezeket a tulajdonságokat használja a Kusto létrehozási idejének felülbírálásához. Ez a funkció hasznos a visszatöltési forgatókönyvekhez

Felhasználási példák

Az alábbi példák feltételezik, hogy telepítette a LightIngest bináris fájljait az operációs rendszerhez. Ha a LightIngest eszközt .NET-eszközként telepítette, cserélje le a LightIngest-et LightIngest-re a példákban.

Előzményadatok betöltése a CreationTime tulajdonsággal

Ha egy meglévő rendszerből betölti az előzményadatokat az Azure Data Explorerbe, minden rekord ugyanazt a betöltési dátumot kapja. Ha a betöltési idő helyett létrehozási idő alapján szeretné particionálásra használni az adatokat, használja 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 azt a szakaszt, amely a használni kívánt időbélyeget tartalmazza.

Az argumentumértékek a következők lehetnek:

  • Az időbélyeg formátumát közvetlenül megelőző állandó szöveg, egyetlen idézőjelben (előtag)
  • Az időbélyeg formátuma standard .NET DateTime jelölésben
  • Az időbélyeget (utótagot) közvetlenül követő állandó szöveg.

Fontos

Ha 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 tényleges Hatókörök egyesítési szabályzatának tulajdonsága igazodik a fájl- vagy blobútvonalak értékeihez.

Examples

  • A dátumidőt a következőképpen tartalmazó blobnév: 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'yyyyyMmdd'.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

  • Töltsön be 10 blobot a megadott tárfiók ACCOUNT mappájában DIR, a tároló CONT-ben, amely megfelel a *.csv.gz mintának.
  • A cél az adatbázis DB, a tábla TABLE, és a betöltési leképezés MAPPING előre létre van hozva 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

  • Az összes blob betöltése a megadott tárfiók ACCOUNT alatt, mappában DIR1/DIR2, tároló CONT alatt, és a mintának megfelelő *.csv.gz
  • A cél az adatbázis DB, a tábla TABLE, és a betöltési leképezés MAPPING előre létre van hozva a célhelyen.
  • A forrásblobok fejlécsort tartalmaznak, ezért az eszköz utasítást kap az egyes blobok első rekordjának elvetésére
  • Az eszköz feltölti az adatokat, és nem várja meg, amíg a betöltési műveletek befejeződnek
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, amely megfelel a mintának *.json
  • Állítsa a célhelyet adatbázisra DB, táblára TABLE, és határozza meg a betöltési leképezést a helyi fájlban MAPPING_FILE_PATH
  • Az eszköz feltölti az adatokat, és nem várja meg, amíg a betöltési műveletek befejeződnek
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, amely megfelel a mintának *.json
  • Állítsa a célhelyet adatbázisra DB, táblára TABLE, és határozza meg a betöltési leképezést a helyi fájlban MAPPING_FILE_PATH
  • Az eszköz feltölti az adatokat, és nem várja meg, amíg a betöltési műveletek befejeződnek
  • A diagnosztikai nyomkövetési fájlokat helyben a LOGS_PATH mappába mentjük.
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"

Hitelesítés felügyelt identitással

A LightIngest három olyan műveletet hajt végre, amelyek a hitelesítéshez használhatják a felügyelt identitást. A felügyelt identitás minden lépésben való használata nem igényli a felügyelt identitás használatát más lépésekben. Minden művelethez meg van adva a kapcsolódó parancssori argumentum .

  • Csatlakozás a Kusto-clusterhez: A betöltés sorba állításához az eszköz egy kapcsolati karakterláncot használ. A "-mi" argumentum használatával adjon meg egy felügyelt identitást, amely a céladatbázisban betöltési jogosultságokkal rendelkező ügyfél virtuális gépen van telepítve.

  • Csatlakozzon az Azure Storage-hoz a blobok letöltéséhez: A "-ingestmi" használatával megadhat egy felügyelt identitást, amely telepítve van a Kusto szolgáltatásra, amely olvasási jogosultságokkal rendelkezik a tárolón.

  • Csatlakozzon az Azure Storage-hoz a tárolóblobok listázásához: A "-storageMi" argumentum használatával adjon meg egy felügyelt identitást, amely telepítve van azon az ügyfél virtuális gépen, amelyen listázási jogosultságok vannak a tárolón. Ha ezt a módszert használja, de az előzőt nem (blobok letöltéséhez csatlakozik az Azure Storage-hoz), a felügyelt identitásnak olvasási jogosultságokkal is rendelkeznie kell, és a rendszer jogkivonatot ad át a Kusto szolgáltatásnak a betöltéshez. Állítsa be mindhárom argumentumot.

  • Last updated on