Azure Data Factory 和 Azure Synapse Analytics 中的查閱活動

發行項
05/24/2023

適用於：Azure Data Factory Azure Synapse Analytics

查閱活動可以從資料處理站和 Synapse 管道所支援的任何資料來源擷取資料集。您可以將其用來動態判斷在後續活動中要處理哪些物件，而不是將物件名稱寫入程式碼。某些物件範例是檔案和資料表。

查閱活動會讀取並傳回組態檔或資料表的內容。也會傳回執行查詢或預存程序的結果。輸出可以是單一值或屬性陣列，可以在後續的複製、轉換或控制流程活動中取用，例如 ForEach 活動。

使用 UI 建立查閱活動

若要在管道中使用查閱活動，請完成下列步驟：

在管道 [活動] 窗格中搜尋查閱，然後將查閱活動拖曳至管道畫布。
在畫布上選取新的查閱活動 (如未選取) 和其 [設定] 索引標籤以編輯詳細資料。
選擇現有的來源資料集，或選取 [新增] 按鈕以建立新的資料集。
從來源資料集識別要包含資料列的選項會根據資料集類型而有所不同。上述範例顯示分隔符號文字資料集的設定選項。以下是 Azure SQL 資料表資料集和 OData 資料集的設定選項範例。

支援的功能

請注意：

查閱活動最多可傳回 5,000 個資料列；如果結果集包含更多記錄，則會傳回前 5,000 個資料列。
查閱活動輸出最多支援 4 MB 的大小，如果大小超過限制，活動將會失敗。
查閱活動在逾時之前的最長持續時間為 24 小時。

注意

當您使用查詢或預存程序來查閱資料時，請務必傳回一個完全相同的結果集。否則，查閱活動會失敗。

查閱活動支援下列資料來源。

類別	資料存放區
Azure	Azure Blob 儲存體
	適用於 NoSQL 的 Azure Cosmos DB
	Azure 資料總管 (Kusto)
	Azure Data Lake Storage Gen1
	Azure Data Lake Storage Gen2 \(部分機器翻譯\)
	適用於 MariaDB 的 Azure 資料庫
	適用於 MySQL 的 Azure 資料庫
	適用於 PostgreSQL 的 Azure 資料庫
	Azure Databricks Delta Lake
	Azure 檔案
	Azure SQL Database
	Azure SQL Database 受控執行個體
	Azure Synapse Analytics
	Azure 資料表儲存體
資料庫	適用於 Oracle 的 Amazon RDS
	適用於 SQL Server 的 Amazon RDS
	Amazon Redshift
	Apache Impala
	Azure SQL Database 受控執行個體
	DB2
	Drill
	Google AdWords
	Google BigQuery
	Greenplum
	HBase
	Hive
	Informix
	MariaDB
	Microsoft Access
	MySQL
	Netezza
	Oracle
	Phoenix
	PostgreSQL
	Presto
	SAP Business Warehouse Open Hub
	SAP Business Warehouse via MDX
	SAP HANA
	SAP 資料表
	SQL Server
	Spark
	Sybase
	Teradata
	Vertica
NoSQL	Cassandra
	Couchbase (預覽)
檔案	Amazon S3
	Amazon S3 相容儲存體
	檔案系統
	FTP
	Google Cloud Storage
	HDFS
	一般 HTTP
	Oracle 雲端儲存空間
	SFTP
一般通訊協定	泛型 OData
	一般 ODBC
	SharePoint Online 清單
服務和應用程式	Amazon Marketplace Web Service
	Concur (預覽)
	Dataverse
	Dynamics 365
	Dynamics AX
	Dynamics CRM
	HubSpot
	Jira
	Azure 資料總管 (Kusto)
	Magento (預覽)
	Marketo (預覽)
	Oracle Eloqua (預覽)
	Oracle Responsys (預覽)
	Oracle Service Cloud (預覽)
	PayPal (預覽)
	QuickBooks (預覽)
	SAP Cloud for Customer (C4C)
	SAP ECC
	Salesforce
	Salesforce Marketing Cloud
	Salesforce 服務雲端
	ServiceNow
	Shopify (預覽)
	Snowflake
	Square (預覽)
	Web 資料表 (HTML 資料表)
	Xero
	Zoho (預覽)

注意

任何標示為「預覽」的連接器都表示您可以試用並提供意見反應給我們。如果您需要依賴解決方案中的預覽連接器，請連絡 Azure 支援。

語法

{
    "name":"LookupActivity",
    "type":"Lookup",
    "typeProperties":{
        "source":{
            "type":"<source type>"
        },
        "dataset":{
            "referenceName":"<source dataset name>",
            "type":"DatasetReference"
        },
        "firstRowOnly":<true or false>
    }
}

類型屬性

名稱	描述	類型	必要項？
資料集	提供查閱的資料集參考。如需詳細資料，請參閱每個對應連接器文章中的＜資料集屬性＞一節。	索引鍵/值組	是
source	包含資料集特定的來源屬性，與複製活動來源相同。如需詳細資料，請參閱每個對應連接器文章中的＜複製活動屬性＞一節。	索引鍵/值組	是
firstRowOnly	指出是否只傳回第一個資料列或傳回所有資料列。	Boolean	否。預設為 `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 管道支援的其他控制流程活動：