從儲存體內嵌
適用於： ✅Microsoft網狀架構✅Azure 數據總管
命令會 .ingest into 藉由從一或多個雲端記憶體檔案「提取」數據，將數據擷取到數據表中。
例如，命令可以從 Azure Blob 儲存體 擷取 1000 個 CSV 格式的 Blob、剖析它們，並將其一起內嵌到單一目標數據表中。
數據會附加至數據表，而不會影響現有的記錄，而不需要修改數據表的架構。
注意
此擷取方法適用於探索和原型設計。 請勿在生產或大量案例中使用。
權限
您必須至少有 資料表擷取許可權 才能執行此命令。
語法
.ingest[async] into table TableName SourceDataLocator [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()）。 擷取較舊的數據時，覆寫預設值很有用，以便正確套用保留原則。 指定時，請確定目標資料表的有效範圍合併原則中的 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 |
針對 ingest-from-query 命令，會指派資料夾給資料表。 如果數據表已經存在，這個屬性會覆寫數據表的資料夾。 | 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 儲存體 / 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 儲存體
下列範例會指示資料庫從 Azure Blob 儲存體 讀取兩個 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。 如需受控識別驗證方法的其他資訊，請參閱 受控識別驗證概觀。
.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')