Sdílet prostřednictvím

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

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

Poznámka:

Zvažte použití příkazů příjmu dat ve frontě , protože nevyžadují instalaci softwaru.

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 ke clusteru Azure Data Exploreru, který spravuje 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 potřebuje LightIngest nezpracovanou velikost dat, aby 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í účastníci
string Kusto připojovací řetězec určení koncového bodu Kusto, který zpracovává příjem dat. Tuto hodnotu uzavřete do dvojitých uvozovek. ✔️
-databáze, -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 uzavřete 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".
-azCli bool Pokud je tato možnost nastavená, pomocí Azure CLI se ověřuje ve službě Kusto. Rozhraní příkazového řádku Azure musí být nainstalované a přihlášené.
-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 nastavené, 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 uzavřete do dvojitých uvozovek.
-vzor string Vzorec, podle kterého se vybírají zdrojové soubory a objekty blob. Podporuje zástupné kóty. Například "*.csv". Tuto hodnotu uzavřete 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 se ignorují. Například "*.csv". Tuto hodnotu uzavřete 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é jste dříve vytvořili 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 nahrávání velkých objemů souborů a datových blobů.
-komprese, -cr double Nápověda k poměru komprese. Užitečné při ingestování komprimovaných souborů a 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.
-seznamJen, -seznam bool Pokud je tato možnost nastavená, zobrazí se pouze položky, které by byly vybrány pro import.
-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ů a 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

Když použijete LightIngest s objekty blob Azure, použije k vylepšení procesu příjmu dat určité vlastnosti metadat objektů blob.

Vlastnost metadat Využití
rawSizeBytes, kustoUncompressedSizeBytes Pokud je nastavená, Funkce LightIngest interpretuje tyto vlastnosti jako nekomprimovanou velikost dat.
kustoCreationTime, kustoCreationTimeUtc LightIngest interpretuje tyto vlastnosti jako časové razítko UTC. Pokud je tato sada nastavená, použije tyto vlastnosti k přepsání času vytvoření v Kusto. Tato funkce je užitečná pro scénáře doplňová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 za LightIngest v příkladech.

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

Když načtete historická data z existujícího systému do Azure Data Exploreru, všechny záznamy získají stejné datum příjmu dat. Pokud chcete data rozdělit podle času vytvoření místo času příjmu -creationTimePattern dat, použijte argument. Argument -creationTimePattern extrahuje CreationTime vlastnost ze souboru nebo cesty k objektu blob. Vzor nemusí odrážet celou cestu k položce, jenom oddíl, který obsahuje č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é

Pokud určíte, že se má čas vytvoření přepsat, ujistěte se, že vlastnost v zásadách sloučení rozsahů cílové tabulky je v souladu s hodnotami v cestách k souborům nebo objektům typu 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

  • Importování všech souborů v cestě PATH, které odpovídají vzoru *.json
  • Nastavte cíl na databázi DB, tabulku TABLEa definujte mapování příjmu dat 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ů

  • Importování všech souborů v cestě PATH, které odpovídají vzoru *.json
  • Nastavte cíl na databázi DB, tabulku TABLEa definujte mapování příjmu dat 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í.
  • Zapsat diagnostické trasovací soubory místně do složky 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

LightIngest provádí tři akce, 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 jiný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žijete tuto metodu, ale ne předchozí metodu (připojíte 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 má použít pro příjem dat. Nastavte všechny tři argumenty.

  • Last updated on