.ingest into
.ingest into 命令會藉由從一或多個雲端記憶體檔案「提取」數據，將數據擷取到數據表中。
例如，命令可以從 Azure Blob 記憶體擷取 1,000 個 CSV 格式的 Blob、剖析它們，並將其一起擷取到單一目標數據表。
數據會附加至數據表，而不會影響現有的記錄，而不需要修改數據表的架構。
注意
此擷取方法適用於探索和原型設計。 請勿在生產或大量案例中使用。
注意
此擷取方法適用於探索和原型設計。 請勿在生產或大量案例中使用。 如需擷取選項的詳細資訊，請參閱 資料擷取概觀。
權限
您必須至少有 數據表擷取程式 許可權，才能執行此命令。
語法
.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]
深入瞭解
參數
| 名字 | 類型 | 必填 | 描述 |
|---|---|---|---|
async |
string |
如果指定，命令會立即傳回，並繼續在背景中擷取。 命令的結果包含 OperationId 值，然後可與 .show operation 命令搭配使用，以擷取擷取完成狀態和結果。 |
|
| TableName | string |
✔️ | 要內嵌數據的數據表名稱。 數據表名稱一律相對於內容中的資料庫。 如果未提供架構對應物件，則會使用內容中的資料庫架構。 |
| SourceDataLocator | string |
✔️ |
注意
我們建議針對 SourceDataLocators使用 模糊字串常值。 服務會在內部追蹤和錯誤訊息中清除認證。
擷取屬性
重要
在佇列擷取 數據會使用 擷取屬性來批處理。 使用愈不同的擷取對應屬性，例如不同的 ConstValue 值，擷取會變成越分散，這可能會導致效能降低。
下表列出並描述支援的屬性，並提供範例：
| 財產 | 描述 | 例 |
|---|---|---|
ingestionMapping |
字串值，指出如何將源檔案中的數據對應至數據表中的實際數據行。 使用相關的對應類型定義 format 值。 請參閱 |
with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]")（已淘汰： avroMapping、csvMapping、jsonMapping） |
ingestionMappingReference |
字串值，指出如何使用具名對應原則物件，將數據從源檔案對應至數據表中的實際數據行。 使用相關的對應類型定義 format 值。 請參閱 |
with (format="csv", ingestionMappingReference = "Mapping1")（已淘汰： avroMappingReference、csvMappingReference、jsonMappingReference） |
creationTime |
日期時間值（格式化為ISO8601字串），以在擷取的數據範圍建立時間使用。 如果未指定，則會使用目前的值 （now()）。 擷取較舊的數據時，覆寫預設值很有用，以便正確套用保留原則。 指定時，請確定目標數據表有效 Extents 合併原則中的 Lookback 屬性， 符合指定的值。 |
with (creationTime="2017-02-13") |
extend_schema |
布爾值，如果指定，指示命令擴充數據表的架構（預設值為 false）。 此選項僅適用於 .append 和 .set-or-append 命令。 唯一允許的架構延伸模組會在結尾新增更多數據行至數據表。 |
如果原始數據表架構 (a:string, b:int)，有效的架構延伸模組會 (a:string, b:int, c:datetime, d:string)，但 (a:string, c:datetime) 無效 |
folder |
針對 從查詢內嵌 命令，要指派給數據表的資料夾。 如果數據表已經存在，這個屬性會覆寫數據表的資料夾。 | with (folder="Tables/Temporary") |
format |
數據格式（請參閱 支援的數據格式）。 | with (format="csv") |
ingestIfNotExists |
如果指定的字串值，如果數據表已經有具有相同值之 ingest-by: 標記的數據，則防止擷取成功。 這可確保等冪數據擷取。 如需詳細資訊，請參閱 內嵌方式：標籤。 |
屬性 with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') 指出，如果標記 ingest-by:Part0001 的數據已經存在，則不會完成目前的擷取。 如果尚未存在，這個新的擷取應該有這個標記集（如果未來的擷取嘗試再次擷取相同的數據。 |
ignoreFirstRecord |
布爾值，如果設定為 true，表示擷取應該忽略每個檔案的第一筆記錄。 如果檔案中的第一筆記錄是數據行名稱，則此屬性適用於 CSV和類似格式的檔案。 根據預設，會假設 false。 |
with (ignoreFirstRecord=false) |
policy_ingestiontime |
布爾值，如果指定，描述是否要在此命令所建立的數據表上啟用 擷取時間原則。 預設值為 true。 |
with (policy_ingestiontime=false) |
recreate_schema |
布爾值，如果指定，描述命令是否可以重新建立數據表的架構。 此屬性僅適用於 .set-or-replace 命令。 如果兩者都已設定，則此屬性的優先順序高於 extend_schema 屬性。 |
with (recreate_schema=true) |
tags |
要與內嵌數據產生關聯的 標籤清單，格式為 JSON 字串 | with (tags="['Tag1', 'Tag2']") |
TreatGzAsUncompressed |
布爾值，如果設定為 true，表示擴展名為 .gz 的檔案不會壓縮。 從 Amazon AWS S3 擷取時，有時需要此旗標。 |
with (treatGzAsUncompressed=true) |
validationPolicy |
JSON 字串，表示在擷取使用 CSV 格式表示的數據期間要執行的驗證。 如需不同選項的說明，請參閱 數據擷取。 |
with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') （這是預設原則） |
zipPattern |
從具有 ZIP 封存的記憶體擷取數據時，請使用此屬性。 這是字串值，表示選取要擷取 ZIP 封存中的檔案時要使用的正則表達式。 封存中的所有其他檔案都會被忽略。 | with (zipPattern="*.csv") |
驗證和授權
每個記憶體連接字串都會指出用來存取記憶體的授權方法。 根據授權方法，主體可能需要授與外部記憶體的許可權，才能執行擷取。
下表列出支持的驗證方法，以及從外部記憶體擷取數據所需的許可權。
| 驗證方法 | Azure Blob Storage / Data Lake Storage Gen2 | Data Lake Storage Gen1 |
|---|---|---|
| 模擬 | 記憶體 Blob 資料讀取器 | 讀者 |
| 共用存取 （SAS） 令牌 | 清單 + 讀取 | Gen1 不支援此驗證方法。 |
| Microsoft Entra 存取令牌 | ||
| 記憶體帳戶存取金鑰 | Gen1 不支援此驗證方法。 | |
| 受控識別 | 記憶體 Blob 資料讀取器 | 讀者 |
返回
命令的結果是一個數據表，其中包含命令所產生的數據分區 （“extents”） 數目一樣多的數據表。 如果未產生任何數據分區，則會傳回具有空白（零值）範圍標識碼的單一記錄。
| 名字 | 類型 | 描述 |
|---|---|---|
| ExtentId | guid |
命令所產生的數據分區的唯一標識符。 |
| ItemLoaded | string |
與此記錄相關的一或多個記憶體檔案。 |
| 期間 | timespan |
執行擷取所需的時間。 |
| HasErrors | bool |
此記錄是否代表擷取失敗。 |
| OperationId | guid |
代表作業的唯一標識碼。 可與 .show operation 命令搭配使用。 |
注意
此命令不會修改要內嵌之數據表的架構。 如有必要，數據會在擷取期間「強制」到這個架構中，而不是另一種方式（忽略額外的數據行，而遺漏的數據行會被視為 Null 值）。
例子
具有共用存取簽章的 Azure Blob 記憶體
下列範例會指示資料庫將兩個 Blob 從 Azure Blob 記憶體讀取為 CSV 檔案，並將其內容內嵌至資料表 T。
... 代表 Azure 記憶體共用存取簽章 （SAS），可提供每個 Blob 的讀取許可權。 模糊字串（字串值前面的 h）是用來確保永遠不會記錄 SAS。
.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 記憶體
下列範例示範如何使用受控識別驗證，從 Azure Blob 記憶體讀取 CSV 檔案，並將其內容內嵌至數據表 T。 驗證會使用指派給 Azure 中 Azure Blob 記憶體的受控識別識別碼（物件標識符）。 如需詳細資訊，請參閱 建立記憶體容器的受控識別。
.ingest into table T ('https://StorageAccount.blob.core.windows.net/Container/file.csv;managed_identity=802bada6-4d21-44b2-9d15-e66b29e4d63e')
Azure Data Lake Storage Gen 2
下列範例用於從 Azure Data Lake Storage Gen 2 擷取數據（ADLSv2）。 這裡所使用的認證 （...） 是記憶體帳戶認證 （共用金鑰），而我們只針對連接字串的秘密部分使用字串模糊化。
.ingest into table T (
'abfss://myfilesystem@contoso.dfs.core.windows.net/path/to/file1.csv;...'
)
Azure Data Lake Storage
下列範例會從 Azure Data Lake Storage （ADLS） 擷取單一檔案。 它會使用使用者的認證來存取 ADLS（因此不需要將記憶體 URI 視為包含秘密）。 它也會示範如何指定擷取屬性。
.ingest into table T ('adl://contoso.azuredatalakestore.net/Path/To/File/file1.ext;impersonate')
with (format='csv')
具有存取金鑰的 Amazon S3
下列範例會使用 存取金鑰標識碼和秘密存取密鑰，從 Amazon S3 擷取單一檔案，。
.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/path/to/file.csv;AwsCredentials=AKIAIOSFODNN7EXAMPLE,wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY')
with (format='csv')
具有預先簽署 URL 的 Amazon S3
下列範例會使用 預先簽署的 URL，從 Amazon S3 擷取單一檔案。
.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
with (format='csv')