從儲存體內嵌
適用於: ✅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 儲存體
下列範例會從 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')