Příjem dat z úložiště
Příkaz .ingest into
ingestuje data do tabulky "načtením" dat z jednoho nebo více souborů cloudového úložiště.
Příkaz může například načíst 1 000 objektů blob ve formátu CSV ze služby Azure Blob Storage, parsovat je a ingestovat je do jedné cílové tabulky.
Data se připojují k tabulce, aniž by to ovlivnilo existující záznamy, a bez úpravy schématu tabulky.
Poznámka:
Tato metoda příjmu dat je určená pro zkoumání a vytváření prototypů. Nepoužívejte ho v produkčních nebo velkoobsadových scénářích.
Oprávnění
Ke spuštění tohoto příkazu musíte mít alespoň oprávnění Table Ingestor .
Syntaxe
.ingest
[async
] into
table
TableName SourceDataLocator [with
(
IngestionPropertyName =
IngestionPropertyValue [,
...] ] )
Přečtěte si další informace o konvencích syntaxe.
Parametry
Název | Type | Požadováno | Popis |
---|---|---|---|
async |
string |
Pokud je zadáno, příkaz se okamžitě vrátí a pokračuje v příjmu dat na pozadí. Výsledky příkazu zahrnují OperationId hodnotu, kterou pak můžete použít s příkazem .show operation k načtení stavu dokončení příjmu dat a výsledků. |
|
TableName | string |
✔️ | Název tabulky, do které se mají ingestovat data. Název tabulky je vždy relativní vzhledem k databázi v kontextu. Pokud není k dispozici žádný objekt mapování schématu, použije se schéma databáze v kontextu. |
SourceDataLocator | string |
✔️ | Jeden nebo čárkami oddělený seznam připojovací řetězec úložiště. Jeden připojovací řetězec musí odkazovat na jeden soubor hostovaný účtem úložiště. Příjem více souborů je možné provést zadáním více připojovací řetězec nebo ingestováním z dotazu externí tabulky. |
Poznámka:
Pro SourceDataLocators doporučujeme používat obfuskované řetězcové literály. Služba vyčistí přihlašovací údaje v interních trasách a chybových zprávách.
Vlastnosti příjmu dat
Důležité
- Ve frontě jsou data příjmu dat dávková pomocí vlastností příjmu dat. Čím více jedinečných vlastností mapování příjmu dat, jako jsou různé hodnoty ConstValue, tím více fragmentovaný příjem dat se stane, což může vést ke snížení výkonu.
Následující tabulka obsahuje seznam vlastností podporovaných Azure Data Explorerem, popisuje je a uvádí příklady:
Vlastnost | Popis | Příklad |
---|---|---|
ingestionMapping |
Řetězcová hodnota, která označuje, jak mapovat data ze zdrojového souboru na skutečné sloupce v tabulce. format Definujte hodnotu s příslušným typem mapování. Viz mapování dat. |
with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]") (zastaralé: avroMapping , csvMapping , jsonMapping ) |
ingestionMappingReference |
Řetězcová hodnota, která označuje, jak mapovat data ze zdrojového souboru na skutečné sloupce v tabulce pomocí pojmenovaného objektu zásad mapování. format Definujte hodnotu s příslušným typem mapování. Viz mapování dat. |
with (format="csv", ingestionMappingReference = "Mapping1") (zastaralé: avroMappingReference , csvMappingReference , jsonMappingReference ) |
creationTime |
Hodnota datetime (formátovaná jako řetězec ISO8601), která se má použít při vytváření ingestovaných rozsahů dat. Pokud není zadáno, použije se aktuální hodnota (now() ). Přepsání výchozí hodnoty je užitečné při ingestování starších dat, aby se zásady uchovávání informací použily správně. Po zadání se ujistěte, že Lookback je vlastnost v efektivní zásadě sloučení rozsahů cílové tabulky zarovnaná se zadanou hodnotou. |
with (creationTime="2017-02-13") |
extend_schema |
Logická hodnota, která v případě zadání dává příkazu pokyn, aby rozšířil schéma tabulky (výchozí hodnota false je ). Tato možnost platí jenom pro .append příkazy a .set-or-append příkazy. Jediná povolená rozšíření schématu mají na konci přidané další sloupce do tabulky. |
Pokud je (a:string, b:int) původní schéma tabulky , platné rozšíření schématu by bylo (a:string, b:int, c:datetime, d:string) , ale (a:string, c:datetime) nebylo by platné. |
folder |
Pro příkazy ingest-from-query se složka, která se má přiřadit k tabulce. Pokud tabulka již existuje, tato vlastnost přepíše složku tabulky. | with (folder="Tables/Temporary") |
format |
Formát dat (viz podporované formáty dat). | with (format="csv") |
ingestIfNotExists |
Řetězcová hodnota, která pokud je zadána, zabrání příjmu dat úspěšně, pokud tabulka již obsahuje data označená značkou ingest-by: se stejnou hodnotou. Tím se zajistí příjem idempotentních dat. Další informace najdete v tématu ingestování podle: značek. |
Vlastnosti with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') označují, že pokud data se značkou ingest-by:Part0001 již existují, nedokončujte aktuální příjem dat. Pokud ještě neexistuje, tento nový příjem dat by měl mít tuto sadu značek (v případě, že se budoucí příjem dat pokusí znovu ingestovat stejná data.) |
ignoreFirstRecord |
Logická hodnota, která pokud je nastavená na true hodnotu , označuje, že příjem dat by měl ignorovat první záznam každého souboru. Tato vlastnost je užitečná pro soubory v CSV a podobných formátech, pokud první záznam v souboru jsou názvy sloupců. Ve výchozím nastavení false se předpokládá. |
with (ignoreFirstRecord=false) |
policy_ingestiontime |
Logická hodnota, která pokud je zadána, popisuje, zda povolit zásady času příjmu dat v tabulce vytvořené tímto příkazem. Výchozí hodnota je true . |
with (policy_ingestiontime=false) |
recreate_schema |
Logická hodnota, která v případě zadání popisuje, zda příkaz může znovu vytvořit schéma tabulky. Tato vlastnost se vztahuje pouze na .set-or-replace příkaz. Tato vlastnost má přednost před extend_schema vlastností, pokud jsou obě nastaveny. |
with (recreate_schema=true) |
tags |
Seznam značek , které se mají přidružit k přijatým datům, formátované jako řetězec JSON | with (tags="['Tag1', 'Tag2']") |
validationPolicy |
Řetězec JSON, který označuje, která ověření se mají spustit během příjmu dat reprezentovaných pomocí formátu CSV. Vysvětlení různých možností najdete v tématu Příjem dat. | with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') (ve skutečnosti se jedná o výchozí zásadu) |
zipPattern |
Tuto vlastnost použijte při ingestování dat z úložiště s archivem ZIP. Jedná se o řetězcovou hodnotu označující 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. | with (zipPattern="*.csv") |
Ověřování a autorizace
Každá připojovací řetězec úložiště označuje metodu autorizace, která se má použít pro přístup k úložišti. V závislosti na metodě autorizace může být potřeba objektu zabezpečení udělit oprávnění k externímu úložišti k provedení příjmu dat.
Následující tabulka uvádí podporované metody ověřování a oprávnění potřebná k ingestování dat z externího úložiště.
Metoda ověřování | Azure Blob Storage / Data Lake Storage Gen2 | Data Lake Storage Gen1 |
---|---|---|
Zosobnění | Čtenář dat v objektech blob služby Storage | Čtenář |
Token sdíleného přístupu (SAS) | Seznam + čtení | Tato metoda ověřování není v Gen1 podporovaná. |
Přístupový token Microsoft Entra | ||
Přístupový klíč účtu úložiště | Tato metoda ověřování není v Gen1 podporovaná. | |
Spravovaná identita | Čtenář dat v objektech blob služby Storage | Čtenář |
Návraty
Výsledkem příkazu je tabulka s tolika záznamy, kolik obsahuje horizontální oddíly dat ("rozsahy") vygenerované příkazem. Pokud nebyly vygenerovány žádné horizontální oddíly dat, vrátí se jeden záznam s prázdným ID rozsahu (s nulovou hodnotou).
Name | Typ | Popis |
---|---|---|
ExtentId | guid |
Jedinečný identifikátor horizontálního oddílu dat, který byl vygenerován příkazem. |
ItemLoaded | string |
Jeden nebo více souborů úložiště, které se vztahují k tomuto záznamu. |
Doba trvání | timespan |
Jak dlouho trvalo příjem dat. |
HasErrors | bool |
Jestli tento záznam představuje selhání příjmu dat, nebo ne. |
Id operace | guid |
Jedinečné ID představující operaci. Lze použít s příkazem .show operation . |
Poznámka:
Tento příkaz neupravuje schéma tabulky, do které se ingestuje. V případě potřeby se data během příjmu dat "přetáčí" do tohoto schématu, ne naopak (nadbytečné sloupce se ignorují a chybějící sloupce se považují za hodnoty null).
Příklady
Azure Blob Storage se sdíleným přístupovým podpisem
Následující příklad dává clusteru pokyn ke čtení dvou objektů blob ze služby Azure Blob Storage jako souborů CSV a ingestování jejich obsahu do tabulky T
. Představuje ...
sdílený přístupový podpis (SAS) azure Storage, který poskytuje přístup pro čtení ke každému objektu blob. Všimněte si také použití obfuskovaných řetězců ( h
před řetězcovými hodnotami), aby se zajistilo, že se SAS nikdy nezaznamená.
.ingest into table T (
h'https://contoso.blob.core.windows.net/container/file1.csv?...',
h'https://contoso.blob.core.windows.net/container/file2.csv?...'
)
Azure Blob Storage se spravovanou identitou
Následující příklad ukazuje, jak číst soubor CSV ze služby Azure Blob Storage a ingestovat jeho obsah do tabulky T
pomocí ověřování spravované identity. Další informace o metodě ověřování spravované identity najdete v tématu Přehled ověřování spravované identity.
.ingest into table T ('https://StorageAccount.blob.core.windows.net/Container/file.csv;managed_identity=802bada6-4d21-44b2-9d15-e66b29e4d63e')
Azure Data Lake Storage Gen2
Následující příklad slouží k ingestování dat z Azure Data Lake Storage Gen2 (ADLSv2). Přihlašovací údaje použité zde (...
) jsou přihlašovací údaje účtu úložiště (sdílený klíč) a pro část tajného kódu připojovací řetězec používáme obfuskaci řetězců.
.ingest into table T (
'abfss://myfilesystem@contoso.dfs.core.windows.net/path/to/file1.csv;...'
)
Azure Data Lake Storage
Následující příklad ingestuje jeden soubor ze služby Azure Data Lake Storage (ADLS). Pro přístup k ADLS používá přihlašovací údaje uživatele (proto není nutné zacházet s identifikátorem URI úložiště jako s tajným kódem). Ukazuje také, jak zadat vlastnosti příjmu dat.
.ingest into table T ('adl://contoso.azuredatalakestore.net/Path/To/File/file1.ext;impersonate')
with (format='csv')
Amazon S3 s přístupovým klíčem
Následující příklad ingestuje jeden soubor z Amazon S3 pomocí ID přístupového klíče a tajného přístupového klíče.
.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/path/to/file.csv;AwsCredentials=AKIAIOSFODNN7EXAMPLE,wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY')
with (format='csv')
Amazon S3 s předem podepsanou adresou URL
Následující příklad ingestuje jeden soubor z Amazon S3 pomocí předsignované adresy URL.
.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
with (format='csv')
Váš názor
https://aka.ms/ContentUserFeedback.
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu:Odeslat a zobrazit názory pro