Sdílet prostřednictvím

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 Exploreru. Nástroj může načíst zdrojová data z místní složky, kontejneru úložiště objektů blob Azure nebo kontejneru Amazon S3.

LightIngest je nejužitečnější, když chcete ingestovat velké množství dat, protože neexistuje žádné časové omezení doby trvání příjmu dat. Je také užitečné, když chcete později dotazovat záznamy podle času, kdy byly vytvořeny, a ne v době, kdy byly ingestovány.

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čujeme ingestovat soubory mezi 100 MB a 1 GB.

Požadavky

Spustit lightingest

Spuštění lightingestu:

  1. Na příkazovém řádku zadejte LightIngest odpovídající argument příkazového řádku.

    Tip

    Pro seznam podporovaných argumentů příkazového řádku zadejte LightIngest /help.

  2. Zadejte ingest- připojovací řetězec do clusteru Azure Data Exploreru, který bude spravovat příjem dat. Uzavřete připojovací řetězec do dvojitých uvozovek a postupujte podle specifikace připojovací řetězec 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 Type Popis Povinní účastníci
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 s dvojitými uvozovkami. ✔️
-database, -db string Název cílové databáze Azure Data Exploreru.
-stůl string Název cílové tabulky Azure Data Exploreru. ✔️
-sourcePath, -source string Umístění zdrojových dat, které 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ězec úložiště. Pass -sourcePath:; zosobnění pro výpis položek ú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 přiřazeným systémem), které se má použít pro připojení. Pro identitu přiřazenou systémem použijte "system".
-ingestWithManagedIdentity, -ingestmi string ID klienta spravované identity (přiřazené uživatelem nebo přiřazeným systémem) nainstalované ve službě Kusto ke stažení z úložiště. Pro identitu přiřazenou systémem použijte "system".
-connectToStorageWithManagedIdentity, -storageMi string ID klienta spravované identity (přiřazené uživatelem nebo přiřazeným systémem) nainstalované na straně klienta k výpisu ze služby Storage.
-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 nastaveno, můžete volitelně zadat identifikátor URI pro přihlášení k Id Microsoft Entra.
-předpona string Pokud se zdrojová data k ingestování nacházejí v úložišti objektů blob, tato předpona adresy URL se sdílí se všemi objekty blob s výjimkou názvu kontejneru.
Například pokud jsou data v MyContainer/Dir1/Dir2, pak by měla být Dir1/Dir2předpona . Tuto hodnotu doporučujeme uzavřít do dvojitých uvozovek.
-vzor string Model, podle kterého se vyberou zdrojové soubory nebo objekty blob. Podporuje zástupné kóty. 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í to být jeden 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í sloupce příjmu dat, které bylo dříve vytvořeno v tabulce. Viz mapování dat.
-creationTimePattern string Při nastavení se používá k extrakci vlastnosti CreationTime ze souboru nebo cesty k objektu blob. Přečtěte si , jak ingestovat data pomocí CreationTime.
-ignoreFirstRow, -ignoreFirst bool Pokud je tato sada nastavená, první záznam každého souboru nebo objektu blob se ignoruje. Pokud například zdrojová data obsahují hlavičky.
-značka string Značky , které se mají 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 poměru komprese. Užitečné při ingestování komprimovaných souborů nebo objektů blob, které pomáhají Azure Data Exploreru vyhodnotit nezpracovanou velikost 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 soubory.
-listOnly, -list bool Pokud je tato možnost nastavená, zobrazí se jenom položky, které by byly vybrány pro příjem dat.
-ingestTimeout integer Časový limit v minutách pro dokončení všech operací ingestování Výchozí hodnota 60je .
-forceSync bool Pokud je nastavená sada, vynutí synchronní příjem dat. Výchozí hodnota falseje .
-interaktivní bool Pokud je nastavená hodnota false, nezobrazí výzvu k potvrzení argumentů. Pro bezobslužné toky a neinteraktivní prostředí. Výchozí hodnota je true.
-dataBatchSize integer Nastaví limit celkové velikosti (MB, nekomprimovaný) každé operace ingestování.
-filesInBatch integer Nastaví limit počtu souborů nebo objektů blob každé operace ingestování.
-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 v aktuálním adresáři nebo je možné je upravit nastavením hodnoty přepínače).

Možnosti specifické pro objekty blob v Azure

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

Vlastnost metadat Využití
rawSizeBytes, kustoUncompressedSizeBytes Pokud je nastavená hodnota, 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 zálohování

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 LightIngest LightIngest je 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 Exploreru obdrží všechny záznamy stejné datum příjmu dat. Pokud chcete povolit dělení dat časem vytvoření, a ne časem příjmu -creationTimePattern dat, můžete tento argument použít. Argument -creationTimePattern extrahuje CreationTime vlastnost ze souboru nebo cesty k objektu blob. Vzor nemusí odrážet celou cestu k položce, pouze oddíl ohraničující časové razítko, které chcete použít.

Hodnoty argumentů musí obsahovat:

  • Konstantní text bezprostředně před formátem časového razítka uzavřený v jednoduchých uvozovkách (předpona)
  • Formát časového razítka ve standardním zápisu .NET DateTime
  • Konstantní text bezprostředně za časovým razítkem (přípona).

Důležité

Při zadávání času vytvoření je třeba přepsat, ujistěte se, že Lookback vlastnost v efektivní zásadě sloučení rozsahů cílové tabulky odpovídá hodnotám 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'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

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

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

  • Ingestování 10 objektů blob v zadaném účtu ACCOUNTúložiště , ve složce DIR, v kontejneru CONTa porovnávání vzoru *.csv.gz
  • Cíl je databáze DB, tabulka TABLEa mapování MAPPING příjmu dat je předem vytvořeno v cíli.
  • 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ě a 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, nikoli řádků záhlaví

  • Ingestování všech objektů blob v zadaném účtu ACCOUNTúložiště , ve složce DIR1/DIR2, v kontejneru CONTa porovnávání vzoru *.csv.gz
  • Cíl je databáze DB, tabulka TABLEa mapování MAPPING příjmu dat je předem vytvořeno v cíli.
  • Zdrojové objekty blob obsahují čáru záhlaví, takže nástroj má dát pokyn, aby vyhodili 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

  • Ingestování všech souborů v cestě PATH, odpovídající vzoru *.json
  • Cíl je databáze DB, tabulka TABLEa mapování příjmu dat je definováno 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"

Ingestování souborů a zápis diagnostických trasovacích souborů

  • Ingestování všech souborů v cestě PATH, odpovídající vzoru *.json
  • Cíl je databáze DB, tabulka TABLEa mapování příjmu dat je definováno 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"

Ověřování pomocí spravované identity

Existují tři akce, které lightingest provádí, které můžou používat spravovanou identitu k ověřování. Použití spravované identity v každém kroku nevyžaduje použití spravované identity v dalších krocích. Pro každou akci je zadaný související argument příkazového řádku.

  • Připojení ke clusteru Kusto: K zařadíte příjem dat do fronty, nástroj používá připojovací řetězec. Pomocí argumentu -mi určete spravovanou identitu nainstalovanou na klientském virtuálním počítači s oprávněními ingestování v cílové databázi.

  • Připojte se ke službě Azure Storage a stáhněte objekty blob: Pomocí příkazu -ingestmi určete spravovanou identitu nainstalovanou ve službě Kusto, která má oprávnění ke čtení v kontejneru úložiště.

  • Připojte se ke službě Azure Storage a zobrazte seznam objektů blob kontejneru: Pomocí argumentu -storageMi určete spravovanou identitu nainstalovanou na klientském virtuálním počítači, která má oprávnění k seznamu kontejneru úložiště. Pokud používáte tuto metodu, ale ne předchozí (připojte se ke službě Azure Storage ke stažení objektů blob), musí mít spravovaná identita také oprávnění ke čtení a token se předá službě Kusto, která se použije k příjmu dat. Proto doporučujeme nastavit všechny tři argumenty.