從儲存體內嵌
.ingest into 命令會從一或多個雲端儲存體檔案中「提取」資料，以將資料內嵌到資料表。
例如，此命令可以從 Azure Blob 儲存體取出 1000 個 CSV 格式的 blob、剖析這些 blob，然後將其一起內嵌到單一目標資料表中。
資料會附加至資料表，而不會影響現有的記錄，且不會修改資料表的結構描述。
注意
此擷取方法適用於探索和原型設計。 請勿在生產或大量案例中使用。
權限
您必須至少有 資料表擷取器 許可權才能執行此命令。
Syntax
.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]
深入瞭解 語法慣例。
參數
| 名稱 | 類型 | 必要 | Description |
|---|---|---|---|
async |
string |
如果指定，命令會立即傳回，並繼續在背景中擷取。 命令的結果包含 OperationId 值，然後可與 命令搭配 .show operation 使用，以擷取擷取完成狀態和結果。 |
|
| TableName | string |
✔️ | 要內嵌數據的數據表名稱。 數據表名稱一律相對於內容中的資料庫。 如果未提供架構對應物件，則會使用內容中的資料庫架構。 |
| SourceDataLocator | string |
✔️ | 記憶體 連接字串的單一或逗號分隔清單。 單一連接字串必須參考儲存體帳戶所主控的單一檔案。 您可以藉由指定多個連接字串，或從外部數據表的查詢擷取，來完成多個檔案的擷取。 |
注意
我們建議針對SourceDataPointer使用模糊字串常值。 服務會清除內部追蹤和錯誤訊息中的認證。
內嵌屬性
重要
- 在佇列擷取 數據中，會使用擷取屬性來批處理。 所使用的更相異擷取對應屬性，例如不同的 ConstValue 值，擷取會變得更分散，這可能會導致效能降低。
下表列出 Azure Data Explorer 支援的屬性、描述這些屬性，並提供範例：
| 屬性 | 描述 | 範例 |
|---|---|---|
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']") |
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 資料讀者 | 讀者 |
傳回
命令的結果是一份資料表，其中包含的記錄數目與命令所產生的資料分區 (「分區」) 數目相同。 如果未產生任何資料分區，則會傳回單一記錄，具有空白 (零值) 分區識別碼。
| 名稱 | 類型 | 描述 |
|---|---|---|
| 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
下列範例會從ADLS Azure Data Lake Storage () 擷取單一檔案。 這會使用使用者的認證來存取 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')
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應