Azure Data Factory 和 Azure Synapse Analytics 中的查閱活動
適用於：
Azure Data Factory Azure Synapse Analytics
提示
試用 Microsoft Fabric 中的 Data Factory，這是適用於企業的全方位分析解決方案。 Microsoft Fabric 涵蓋從資料移動到資料科學、即時分析、商業智慧和報告的所有項目。 了解如何免費開始新的試用！
查閱活動可以從資料處理站和 Synapse 管道所支援的任何資料來源擷取資料集。 您可以將其用來動態判斷在後續活動中要處理哪些物件，而不是將物件名稱寫入程式碼。 某些物件範例是檔案和資料表。
查閱活動會讀取並傳回組態檔或資料表的內容。 也會傳回執行查詢或預存程序的結果。 輸出可以是單一值或屬性陣列，可以在後續的複製、轉換或控制流程活動中取用，例如 ForEach 活動。
使用 UI 建立查閱活動
若要在管道中使用查閱活動，請完成下列步驟：
在管道 [活動] 窗格中搜尋查閱，然後將查閱活動拖曳至管道畫布。
在畫布上選取新的查閱活動 (如未選取) 和其 [設定] 索引標籤以編輯詳細資料。
選擇現有的來源資料集，或選取 [新增] 按鈕以建立新的資料集。
從來源資料集識別要包含資料列的選項會根據資料集類型而有所不同。 上述範例顯示分隔符號文字資料集的設定選項。 以下是 Azure SQL 資料表資料集和 OData 資料集的設定選項範例。
支援的功能
請注意以下要點：
- 查閱活動最多可傳回 5,000 個資料列；如果結果集包含更多記錄，則會傳回前 5,000 個資料列。
- 查閱活動輸出最多支援 4 MB 的大小，如果大小超過限制，活動將會失敗。
- 查閱活動在逾時之前的最長持續時間為 24 小時。
注意
當您使用查詢或預存程序來查閱資料時，請務必傳回一個完全相同的結果集。 否則，查閱活動會失敗。
查閱活動支援下列資料來源。
注意
任何標示為「預覽」的連接器都表示您可以試用並提供意見反應給我們。 如果您需要依賴解決方案中的預覽連接器，請連絡 Azure 支援。
語法
{
"name":"LookupActivity",
"type":"Lookup",
"typeProperties":{
"source":{
"type":"<source type>"
},
"dataset":{
"referenceName":"<source dataset name>",
"type":"DatasetReference"
},
"firstRowOnly":<true or false>
}
}
類型屬性
| 名稱 | 描述 | 類型 | 是必要的嗎? |
|---|---|---|---|
| 資料集 | 提供查閱的資料集參考。 如需詳細資料，請參閱每個對應連接器文章中的＜資料集屬性＞一節。 | 索引鍵/值組 | Yes |
| 來源 | 包含資料集特定的來源屬性，與複製活動來源相同。 如需詳細資料，請參閱每個對應連接器文章中的＜複製活動屬性＞一節。 | 索引鍵/值組 | Yes |
| firstRowOnly | 指出是否只傳回第一個資料列或傳回所有資料列。 | 布林值 | 否。 預設值為 true。 |
注意
- 不支援 ByteArray 類型的來源資料行。
- 資料集定義不支援結構。 針對文字格式檔案，可以使用標頭資料列來提供資料行名稱。
- 如果您的查閱來源是 JSON 檔案，不支援用於調整 JSON 物件的
jsonPathDefinition設定。 將會擷取整個物件。
使用查閱活動結果
查閱結果會在活動執行結果的 output 區段中傳回。
當
firstRowOnly設為true(預設值)，輸出格式如下列程式碼所示。 查閱結果就在固定的firstRow索引鍵底下。 若要在後續活動中使用結果，請使用@{activity('LookupActivity').output.firstRow.table}模式。{ "firstRow": { "Id": "1", "schema":"dbo", "table":"Table1" } }當
firstRowOnly設為false，輸出格式如下列程式碼所示。count欄位會指出傳回多少筆記錄。 詳細的值會顯示在固定value陣列下。 在這種情況下，查閱活動後面會接著 Foreach 活動。 您可以使用@activity('MyLookupActivity').output.value模式，將value陣列傳遞至 ForEach 活動的items欄位。 若要存取value陣列中的元素，請使用下列語法：@{activity('lookupActivity').output.value[zero based index].propertyname}。 例如@{activity('lookupActivity').output.value[0].schema}。{ "count": "2", "value": [ { "Id": "1", "schema":"dbo", "table":"Table1" }, { "Id": "2", "schema":"dbo", "table":"Table2" } ] }
範例
在此範例中，管道包含兩個活動：查閱和複製。 複製活動會將資料從 Azure SQL Database 執行個體中的 SQL 資料表複製到 Azure Blob 儲存體。 SQL 資料表的名稱會儲存在 Blob 儲存體的 JSON 檔案中。 查閱活動在執行階段會查閱表格名稱。 使用這種方法可動態修改 JSON。 您不需要重新部署管線或資料集。
此範例僅示範查閱第一個資料列。 若要查閱所有資料列並鏈結結果與 ForEach 活動，請參閱大量複製多個資料表中的範例。
管線
- 查閱活動會設定為使用 LookupDataset，它會參考 Azure Blob 儲存體中的位置。 查閱活動會從這個位置的 JSON 檔案讀取 SQL 資料表的名稱。
- 複製活動會使用查閱活動的輸出，亦即 SQL 資料表的名稱。 SourceDataset 中的 tableName 屬性會設定為使用查閱活動的輸出。 複製活動會將資料從 SQL 資料表複製到 Azure Blob 儲存體 中的位置。 此位置會由 SinkDataset 屬性指定。
{
"name": "LookupPipelineDemo",
"properties": {
"activities": [
{
"name": "LookupActivity",
"type": "Lookup",
"dependsOn": [],
"policy": {
"timeout": "7.00:00:00",
"retry": 0,
"retryIntervalInSeconds": 30,
"secureOutput": false,
"secureInput": false
},
"userProperties": [],
"typeProperties": {
"source": {
"type": "JsonSource",
"storeSettings": {
"type": "AzureBlobStorageReadSettings",
"recursive": true
},
"formatSettings": {
"type": "JsonReadSettings"
}
},
"dataset": {
"referenceName": "LookupDataset",
"type": "DatasetReference"
},
"firstRowOnly": true
}
},
{
"name": "CopyActivity",
"type": "Copy",
"dependsOn": [
{
"activity": "LookupActivity",
"dependencyConditions": [
"Succeeded"
]
}
],
"policy": {
"timeout": "7.00:00:00",
"retry": 0,
"retryIntervalInSeconds": 30,
"secureOutput": false,
"secureInput": false
},
"userProperties": [],
"typeProperties": {
"source": {
"type": "AzureSqlSource",
"sqlReaderQuery": {
"value": "select * from [@{activity('LookupActivity').output.firstRow.schema}].[@{activity('LookupActivity').output.firstRow.table}]",
"type": "Expression"
},
"queryTimeout": "02:00:00",
"partitionOption": "None"
},
"sink": {
"type": "DelimitedTextSink",
"storeSettings": {
"type": "AzureBlobStorageWriteSettings"
},
"formatSettings": {
"type": "DelimitedTextWriteSettings",
"quoteAllText": true,
"fileExtension": ".txt"
}
},
"enableStaging": false,
"translator": {
"type": "TabularTranslator",
"typeConversion": true,
"typeConversionSettings": {
"allowDataTruncation": true,
"treatBooleanAsNumber": false
}
}
},
"inputs": [
{
"referenceName": "SourceDataset",
"type": "DatasetReference",
"parameters": {
"schemaName": {
"value": "@activity('LookupActivity').output.firstRow.schema",
"type": "Expression"
},
"tableName": {
"value": "@activity('LookupActivity').output.firstRow.table",
"type": "Expression"
}
}
}
],
"outputs": [
{
"referenceName": "SinkDataset",
"type": "DatasetReference",
"parameters": {
"schema": {
"value": "@activity('LookupActivity').output.firstRow.schema",
"type": "Expression"
},
"table": {
"value": "@activity('LookupActivity').output.firstRow.table",
"type": "Expression"
}
}
}
]
}
],
"annotations": [],
"lastPublishTime": "2020-08-17T10:48:25Z"
}
}
查閱資料集
查閱資料集會是 Azure 儲存體查閱資料夾中的 sourcetable.json 檔案 (此檔案是由 AzureBlobStorageLinkedService 類型指定)。
{
"name": "LookupDataset",
"properties": {
"linkedServiceName": {
"referenceName": "AzureBlobStorageLinkedService",
"type": "LinkedServiceReference"
},
"annotations": [],
"type": "Json",
"typeProperties": {
"location": {
"type": "AzureBlobStorageLocation",
"fileName": "sourcetable.json",
"container": "lookup"
}
}
}
}
複製活動的來源資料集
來源資料集會使用查閱活動的輸出，亦即 SQL 資料表的名稱。 複製活動會將資料從此 SQL 資料表複製到 Azure Blob 儲存體 中的位置。 此位置會由接收資料集指定。
{
"name": "SourceDataset",
"properties": {
"linkedServiceName": {
"referenceName": "AzureSqlDatabase",
"type": "LinkedServiceReference"
},
"parameters": {
"schemaName": {
"type": "string"
},
"tableName": {
"type": "string"
}
},
"annotations": [],
"type": "AzureSqlTable",
"schema": [],
"typeProperties": {
"schema": {
"value": "@dataset().schemaName",
"type": "Expression"
},
"table": {
"value": "@dataset().tableName",
"type": "Expression"
}
}
}
}
複製活動的接收資料集
複製活動會將資料從 SQL 資料表複製到 Azure 儲存體中 csv 資料夾內的 filebylookup.csv 檔案。 此檔案會由 AzureBlobStorageLinkedService 屬性指定。
{
"name": "SinkDataset",
"properties": {
"linkedServiceName": {
"referenceName": "AzureBlobStorageLinkedService",
"type": "LinkedServiceReference"
},
"parameters": {
"schema": {
"type": "string"
},
"table": {
"type": "string"
}
},
"annotations": [],
"type": "DelimitedText",
"typeProperties": {
"location": {
"type": "AzureBlobStorageLocation",
"fileName": {
"value": "@{dataset().schema}_@{dataset().table}.csv",
"type": "Expression"
},
"container": "csv"
},
"columnDelimiter": ",",
"escapeChar": "\\",
"quoteChar": "\""
},
"schema": []
}
}
sourcetable.json
您可以針對 sourcetable.json 檔案使用下列兩種格式。
物件集合
{
"Id":"1",
"schema":"dbo",
"table":"Table1"
}
{
"Id":"2",
"schema":"dbo",
"table":"Table2"
}
物件陣列
[
{
"Id": "1",
"schema":"dbo",
"table":"Table1"
},
{
"Id": "2",
"schema":"dbo",
"table":"Table2"
}
]
限制和因應措施
以下是查閱活動和因應措施建議的一些限制。
| 限制 | 因應措施 |
|---|---|
| 查閱活動最多可有 5,000 個資料列，大小上限為 4 MB。 | 設計兩個層級的管線，其中外部管線會逐一查看內部管線，並擷取不超過最大資料列或大小的資料。 |
相關內容
請參閱 Azure Data Factory 和 Synapse 管道支援的其他控制流程活動：
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應