Příjem dat z úložiště

Platí pro: ✅Microsoft Fabric✅Azure Data Explorer

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] intotableTableNameSourceDataLocator [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 dotazuexterní 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 podporovaných vlastností 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 falseje ). 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ých více sloupců 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 truehodnotu , 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 CSVa 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']")
TreatGzAsUncompressed	Logická hodnota, která pokud je nastavena na true, označuje, že soubory s příponou .gz nejsou komprimovány. Tento příznak je někdy potřeba při ingestování z Amazon AWS S3.	with (treatGzAsUncompressed=true)
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}') (toto je výchozí zásada)
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 se ignorují.	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).

Název	Type	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	Zda tento záznam představuje selhání příjmu dat.
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á vaší databázi 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. Obfuskované řetězce (h před řetězcovými hodnotami) slouží k zajištění toho, aby se SAS nikdy nezaznamenával.

.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. Ověřování používá ID spravované identity (ID objektu) přiřazené službě Azure Blob Storage v Azure. Další informace najdete v tématu Vytvoření spravované identity pro kontejnery úložiště.

.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')

Související obsah

• formáty dat podporované pro příjem dat
• příchozí příjem dat
• Ingestování z dotazu (.set, .append, .set-or-append, .set-or-replace)
• příkaz .show selhání příjmu dat
• .show mapování příjmu dat