Sdílet prostřednictvím

.ingestování do

  • Článek

Platí pro: ✅Microsoft Fabric✅Azure Data Explorer

Příkaz .ingest into ingestuje data do tabulky "vyžádání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.

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. Další informace o možnostech příjmu dat najdete v tématu Přehled příjmu dat.

Dovolení

Ke spuštění tohoto příkazu musíte mít alespoň oprávnění ingestoru tabulky.

Syntax

.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]

Přečtěte si další informace o konvencích syntaxe .

Parametry

Jméno Typ Požadovaný 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í hodnotu OperationId, kterou pak můžete použít s příkazem .show operation k načtení stavu a výsledků dokončení příjmu dat.
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ích řetězců úložiště . Jeden připojovací řetězec musí odkazovat na jeden soubor hostovaný účtem úložiště. Příjem více souborů lze provést zadáním více připojovacích řetězců nebo ingestováním z dotazuexterní tabulky.

Poznámka

Doporučujeme použít obfuskované řetězcové literály pro SourceDataLocators. 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ý

V příjmu dat ve frontě jsou data 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. Definujte format 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í. Definujte format 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 vlastnost v efektivní Rozsah y cílové tabulky je 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 je false). Tato možnost se vztahuje pouze na příkazy .append a .set-or-append. Jediná povolená rozšíření schématu mají na konci přidaných více sloupců do tabulky. Pokud je původní schéma tabulky (a:string, b:int), platné rozšíření schématu by bylo (a:string, b:int, c:datetime, d:string), ale (a:string, c:datetime) by nebylo platné.
folder Pro ingestování z dotazu příkazy, 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 zadaná, 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čky. 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 nastavena na true, 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é formáty, pokud první záznam v souboru jsou názvy sloupců. Ve výchozím nastavení se předpokládá false. 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 příkaz .set-or-replace. Tato vlastnost má přednost před vlastností extend_schema, pokud jsou obě nastaveny. with (recreate_schema=true)
tags Seznam značek pro přidružení k přijatým datům formátovaným 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 objektů blob služby Storage Čtenář
tokenu 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é identity Čtenář dat objektů 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).

Jméno 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.
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) služby 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é tady (...) jsou přihlašovací údaje účtu úložiště (sdílený klíč) a pro část připojovacího řetězce 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=EXAMPLEKEY')
  with (format='csv')

Amazon S3 s předem podepsanou adresou URL

Následující příklad ingestuje jeden soubor z Amazon S3 pomocí předSigned URL.

.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
  with (format='csv')

Související obsah