共用方式為


從儲存體內嵌

適用於: ✅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\"}}]")
(已淘汰: avroMappingcsvMappingjsonMapping)
ingestionMappingReference 字串值,該值指出如何使用具名對應原則物件,將來源檔案的資料對應到資料表中的實際資料行。 使用相關對應類型定義 format 值。 請參閱資料對應 with (format="csv", ingestionMappingReference = "Mapping1")
(已淘汰: avroMappingReferencecsvMappingReferencejsonMappingReference)
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')