Ingestování dat do Azure Data Exploreru s využitím nástroje LightIngest

  • Článek

LightIngest je nástroj příkazového řádku pro ad hoc příjem dat do Azure Data Explorer. Nástroj může načíst zdrojová data z místní složky, kontejneru úložiště objektů blob v Azure nebo kbelíku Amazon S3.

Funkce LightIngest je nejužitečnější, když chcete ingestovat velké množství dat, protože doba trvání příjmu dat není nijak časově omezená. Je také užitečná, když chcete později dotazovat záznamy podle času, kdy byly vytvořeny, a ne podle času, kdy byly přijaty.

Příklad automatického vygenerování příkazu LightIngest najdete v tématu ingestování historických dat.

Poznámka

Příjem dat podporuje maximální velikost souboru 6 GB. Doporučuje se ingestovat soubory od 100 MB do 1 GB.

Požadavky

Spustit LightIngest

Spuštění LightIngestu:

  1. Na příkazovém řádku zadejte LightIngest a potom příslušný argument příkazového řádku.

    Tip

    Seznam podporovaných argumentů příkazového řádku zobrazíte zadáním LightIngest /help.

  2. Zadejte ingest- a potom připojovací řetězec do clusteru Azure Data Explorer, který bude spravovat příjem dat. Uzavřete připojovací řetězec do dvojitých uvozovek a postupujte podle specifikace připojovacích řetězců Kusto.

    Příklad:

    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

Doporučení k výkonu

  • Pokud chcete co nejlépe spravovat zatížení příjmu dat a zotavit se z přechodných chyb, použijte koncový bod příjmu dat na adrese https://ingest-{yourClusterNameAndRegion}.kusto.windows.net.

  • Pro optimální výkon příjmu dat je potřeba nezpracovaná velikost dat, aby LightIngest mohl odhadnout nekomprimovanou velikost místních souborů. LightIngest ale nemusí být schopen správně odhadnout nezpracovanou velikost komprimovaných objektů blob bez jejich prvního stažení. Proto při ingestování komprimovaných objektů blob nastavte rawSizeBytes vlastnost metadat objektů blob na nekomprimovanou velikost dat v bajtech.

Argumenty příkazového řádku

Argument Typ Popis Povinné
string Kusto připojovací řetězec určení koncového bodu Kusto, který zpracovává příjem dat. Tato hodnota by měla být uzavřena dvojitými uvozovkami. ✔️
-database, -db string Název cílové databáze Azure Data Explorer.
-Tabulka string Název cílové tabulky Azure Data Explorer. ✔️
-sourcePath, -source string Umístění zdrojových dat, kterým může být buď místní cesta k souboru, kořenový identifikátor URI kontejneru objektů blob Azure nebo identifikátor URI kontejneru Amazon S3. Pokud jsou data uložená v objektech blob Azure, musí identifikátor URI obsahovat klíč účtu úložiště nebo sdílený přístupový podpis (SAS). Pokud jsou data v kbelíku S3, musí identifikátor URI obsahovat klíč přihlašovacích údajů. Tuto hodnotu doporučujeme uzavřít do dvojitých uvozovek. Další informace najdete v tématu Připojovací řetězce úložiště. Pass -sourcePath:; zosobnit a vypsat položky úložiště Azure s uživatelskými oprávněními (autorizace výzvy uživatele). ✔️
-managedIdentity, -mi string ID klienta spravované identity (přiřazené uživatelem nebo systémem), které se mají použít pro připojení. Pro identitu přiřazenou systémem použijte "system".
-ingestWithManagedIdentity, -imgestmi string ID klienta spravované identity (přiřazené uživatelem nebo systémem), které se mají použít pro připojení. Pro identitu přiřazenou systémem použijte "system".
-connectToStorageWithUserAuth, -storageUserAuth string Ověřte se ve službě úložiště zdroje dat pomocí přihlašovacích údajů uživatele. Možnosti pro tuto hodnotu jsou PROMPT nebo DEVICE_CODE.
-connectToStorageLoginUri, -storageLoginUri string Pokud -connectToStorageWithUserAuth je nastavená, můžete volitelně zadat identifikátor URI Microsoft Entra ID přihlášení.
-Předponu string Pokud se zdrojová data k ingestování nacházejí v úložišti objektů blob, sdílí tuto předponu adresy URL všechny objekty blob s výjimkou názvu kontejneru.
Pokud jsou například data v MyContainer/Dir1/Dir2, pak by předpona měla být Dir1/Dir2. Tuto hodnotu doporučujeme uzavřít do dvojitých uvozovek.
-Vzor string Vzor, podle kterého se vybírají zdrojové soubory nebo objekty blob Podporuje zástupné cardy. Například, "*.csv". Tuto hodnotu doporučujeme uzavřít do dvojitých uvozovek.
-zipPattern string Regulární výraz, který se má použít při výběru souborů v archivu ZIP k ingestování. Všechny ostatní soubory v archivu budou ignorovány. Například, "*.csv". Tuto hodnotu doporučujeme uzavřít do dvojitých uvozovek.
-format, -f string Formát zdrojových dat. Musí být jedním z podporovaných formátů.
-ingestionMappingPath, -mappingPath string Cesta k místnímu souboru pro mapování sloupců příjmu dat. Viz mapování dat.
-ingestionMappingRef, -mappingRef string Název mapování sloupců příjmu dat, které bylo dříve vytvořeno v tabulce. Viz mapování dat.
-creationTimePattern string Při nastavení se použije k extrahování vlastnosti CreationTime ze souboru nebo cesty k objektu blob. Viz Jak ingestovat data pomocí CreationTime.
-ignoreFirstRow, -ignoreFirst bool Pokud je tato možnost nastavená, první záznam každého souboru nebo objektu blob se ignoruje. Například pokud zdrojová data obsahují hlavičky.
-Značku string Značky , které chcete přidružit k přijatým datům. Je povoleno více výskytů.
-dontWait bool Pokud je nastavená hodnota true, nečeká na dokončení příjmu dat. Užitečné při ingestování velkých objemů souborů nebo objektů blob.
-compression, -cr double Nápověda k kompresnímu poměru. Užitečné při ingestování komprimovaných souborů nebo objektů blob, které azure Data Explorer vyhodnotit velikost nezpracovaných dat. Vypočítá se jako původní velikost dělená komprimovanou velikostí.
-limit, -l integer Pokud je tato možnost nastavená, omezí příjem dat na první N souborů.
-listOnly, -list bool Pokud je tato možnost nastavená, zobrazí pouze položky, které by byly vybrány pro příjem dat.
-ingestTimeout integer Vypršení časového limitu v minutách pro dokončení všech operací ingestování Výchozí hodnota je 60.
-forceSync bool Pokud je nastavená, vynutí synchronní příjem dat. Výchozí hodnota je false.
-Interaktivní bool Pokud je nastavená hodnota false, nezobrazí výzvu k potvrzení argumentů. Pro bezobslužné toky a neinteraktivní prostředí Výchozí je true.
-dataBatchSize integer Nastaví limit celkové velikosti (MB, nekomprimované) každé operace příjmu.
-filesInBatch integer Nastaví limit počtu souborů nebo objektů blob pro každou operaci příjmu.
-devTracing, -trace string Pokud je tato možnost nastavená, zapisují se diagnostické protokoly do místního adresáře (ve výchozím nastavení RollingLogs do aktuálního adresáře nebo se dají upravit nastavením hodnoty přepínače).

Funkce specifické pro objekty blob v Azure

Při použití s objekty blob Azure používá LightIngest k rozšíření procesu příjmu dat určité vlastnosti metadat objektu blob.

Vlastnost metadat Využití
rawSizeBytes, kustoUncompressedSizeBytes Pokud je nastavená, bude interpretována jako nekomprimovaná velikost dat.
kustoCreationTime, kustoCreationTimeUtc Interpretováno jako časové razítko UTC. Pokud je tato možnost nastavená, použije se k přepsání času vytvoření v Kusto. Užitečné pro scénáře backfillingu

Příklady použití

Následující příklady předpokládají, že jste nainstalovali binární soubory LightIngest pro váš operační systém. Pokud jste nainstalovali LightIngest jako nástroj .NET, nahraďte LightIngestLightIngest ho v příkladech.

Ingestování historických dat pomocí vlastnosti CreationTime

Při načítání historických dat z existujícího systému do Azure Data Explorer obdrží všechny záznamy stejné datum příjmu dat. Pokud chcete povolit dělení dat podle času vytvoření, nikoli doby příjmu -creationTimePattern dat, můžete použít argument . Argument -creationTimePattern extrahuje CreationTime vlastnost z cesty k souboru nebo objektu blob. Tento vzor nemusí odrážet celou cestu k položce, ale jenom část ohraničující časové razítko, které chcete použít.

Hodnoty argumentů musí obsahovat:

  • Konstantní text bezprostředně předcházející formátu časového razítka uzavřený v jednoduchých uvozovkách (předpona)
  • Formát časového razítka ve standardní notaci .NET DateTime
  • Konstantní text bezprostředně za časovým razítkem (příponou).

Důležité

Při zadávání, že se má přepsat čas vytvoření, ujistěte se, že Lookback je vlastnost v efektivních zásadách sloučení Rozsahů cílové tabulky zarovnaná s hodnotami v cestě k souboru nebo objektu blob.

Příklady

  • Název objektu blob, který obsahuje datum a čas takto: historicalvalues19840101.parquet (časové razítko je čtyři číslice pro rok, dvě číslice pro měsíc a dvě číslice pro den v měsíci),

    Hodnota -creationTimePattern argumentu je součástí názvu souboru: "'historicalvalues'yyyyMMmdd'.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

  • Identifikátor URI objektu blob, který odkazuje na hierarchickou strukturu složek, jako je https://storageaccount/mycontainer/myfolder/2002/12/01/blobname.extension,

    Hodnota argumentu -creationTimePattern je součástí struktury složky: "'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

Ingestování objektů blob pomocí klíče účtu úložiště nebo tokenu SAS

  • Ingestujte 10 objektů blob v zadaném účtu ACCOUNTúložiště , ve složce DIR, v kontejneru CONTa odpovídající vzor *.csv.gz
  • Cíl je databáze DB, tabulka TABLEa mapování MAPPING příjmu dat je předem na cílovém místě.
  • Nástroj počká na dokončení operací ingestování.
  • Všimněte si různých možností pro zadání cílové databáze a klíče účtu úložiště vs. tokenu SAS.
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

Ingestování všech objektů blob v kontejneru, bez řádků záhlaví

  • Ingestujte všechny objekty blob v zadaném účtu ACCOUNTúložiště , ve složce DIR1/DIR2, v kontejneru CONTa odpovídající vzor *.csv.gz
  • Cíl je databáze DB, tabulka TABLEa mapování MAPPING příjmu dat je předem na cílovém místě.
  • Zdrojové objekty blob obsahují řádek záhlaví, takže nástroj má pokyn, aby vyřadil první záznam každého objektu blob.
  • Nástroj publikuje data pro příjem dat a nečeká na dokončení operací ingestování.
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

Ingestování všech souborů JSON z cesty

  • Ingestovat všechny soubory v cestě PATH, které odpovídají vzoru *.json
  • Cíl je databáze DB, tabulka TABLEa mapování příjmu dat je definované v místním souboru. MAPPING_FILE_PATH
  • Nástroj publikuje data pro příjem dat a nečeká na dokončení operací ingestování.
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"

Příjem souborů a zápis diagnostických trasovacích souborů

  • Ingestovat všechny soubory v cestě PATH, které odpovídají vzoru *.json
  • Cíl je databáze DB, tabulka TABLEa mapování příjmu dat je definované v místním souboru. MAPPING_FILE_PATH
  • Nástroj publikuje data pro příjem dat a nečeká na dokončení operací ingestování.
  • Soubory trasování diagnostiky se zapisují místně ve složce. 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"