Azure Data Factory 和 Azure Synapse Analytics 中的 Web 活動

發行項
12/09/2023

適用于： Azure Data Factory Azure Synapse Analytics

提示

試用 Microsoft Fabric 中的 Data Factory，這是適用于企業的單一分析解決方案。 Microsoft Fabric 涵蓋從資料移動到資料科學、即時分析、商業智慧和報告等所有專案。瞭解如何免費啟動新的試用版！

Web 活動可用來從 Azure Data Factory 或 Synapse 管線呼叫自訂 REST 端點。您可以傳遞資料集和連結服務，以供活動取用和存取。

注意

利用自我裝載整合執行時間，支援叫用裝載在專用虛擬網路中的 URL。整合執行時間應該會有 URL 端點的視線。

注意

支援的輸出回應承載大小上限為 4 MB。

使用 UI 建立 Web 活動

若要在管線中使用 Web 活動，請完成下列步驟：

在 [管線活動] 窗格中搜尋 Web，並將 Web 活動拖曳至管線畫布。
如果尚未選取，請選取畫布上的新 Web 活動，以及其設定索引標籤，以編輯其詳細資料。
指定 URL，可以是常值 URL 字串，或動態運算式、函式、系統變數或來自其他活動的輸出的任何組合。提供要求提交的其他詳細資料。
使用活動的輸出做為任何其他活動的輸入，並在目的地活動支援動態內容的任何位置參考輸出。

語法

{
   "name":"MyWebActivity",
   "type":"WebActivity",
   "typeProperties":{
      "method":"Post",
      "url":"<URLEndpoint>",
      "httpRequestTimeout": "00:01:00"
      "connectVia": {
          "referenceName": "<integrationRuntimeName>",
          "type": "IntegrationRuntimeReference"
      }
      "headers":{
         "Content-Type":"application/json"
      },
      "authentication":{
         "type":"ClientCertificate",
         "pfx":"****",
         "password":"****"
      },
      "datasets":[
         {
            "referenceName":"<ConsumedDatasetName>",
            "type":"DatasetReference",
            "parameters":{
               ...
            }
         }
      ],
      "linkedServices":[
         {
            "referenceName":"<ConsumedLinkedServiceName>",
            "type":"LinkedServiceReference"
         }
      ]
   }
}

類型屬性

屬性	說明	允許的值	必要
NAME	Web 活動的名稱	String	Yes
type	必須設定為 WebActivity 。	String	Yes
method	目標端點的 REST API 方法。	字串。支援的類型：「GET」、「POST」、「PUT」、「PATCH」、「DELETE」	Yes
URL	目標端點和路徑	String （或 expression with resultType of string）的運算式。如果活動未收到來自端點的回應，活動將會逾時 1 分鐘，並出現錯誤。您可以藉由更新 HTTPRequestTimeout 屬性，將此回應逾時增加至 10 分鐘	Yes
HTTPRequestTimeout	回應逾時持續時間	hh：mm：ss，最大值為 00：10：00。如果未明確指定預設值為 00：01：00	No
標題	傳送至要求的標頭。例如，若要在要求上設定語言和類型： `"headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }` 。	String （或 expression with resultType of string）	No
本文	表示傳送至端點的承載。	String （或 expression with resultType of string）的運算式。請參閱要求承載架構一節中要求承載的架構。	POST/PUT/PATCH 方法的必要專案。 DELETE 方法的選擇性。
驗證 (authentication)	用於呼叫端點的驗證方法。支援的類型為「基本、用戶端憑證、系統指派的受控識別、使用者指派的受控識別、服務主體」。如需詳細資訊，請參閱驗證一節。如果不需要驗證，請排除此屬性。	String （或 expression with resultType of string）	No
turnOffAsync	在 HTTP 202 回應的回應標頭中停用叫用 HTTP GET on location 欄位的選項。如果設定為 true，它會停止在回應標頭中指定的 HTTP 位置上叫用 HTTP GET。如果設定 false，它會繼續在 HTTP 回應標頭中指定的位置上叫用 HTTP GET 呼叫。	允許的值為 false（預設值）和 true。	No
disableCertValidation	移除伺服器端憑證驗證（除非您連線到不使用標準 CA 憑證的信任伺服器），否則不建議這麼做。	允許的值為 false（預設值）和 true。	No
datasets	傳遞至端點的資料集清單。	資料集參考的陣列。可以是空陣列。	Yes
linkedServices	傳遞至端點的連結服務清單。	連結服務參考的陣列。可以是空陣列。	Yes
connectVia	要用來連接到資料存放區的整合執行時間。您可以使用 Azure 整合執行時間或自我裝載整合執行時間（如果您的資料存放區位於私人網路中）。如果未指定此屬性，服務會使用預設的 Azure 整合執行時間。	整合執行時間參考。	No

注意

Web 活動叫用的 REST 端點必須傳回 JSON 類型的回應。如果活動未收到來自端點的回應，活動將會逾時 1 分鐘，並出現錯誤。對於支援非同步要求-回復模式的端點，Web 活動會繼續等候，而不會逾時（最多 7 天），或直到端點發出作業完成的訊號為止。

下表顯示 JSON 內容的需求：

值類型	要求本文	回應本文
JSON 物件	支援	支援
JSON 陣列	支援（目前，JSON 陣列因 Bug 而無法運作。修正正在進行中。	不支援
JSON 值	支援	不支援
非 JSON 類型	不支援	不支援

驗證

以下是 Web 活動中支援的驗證類型。

無

如果不需要驗證，請勿包含「authentication」屬性。

基本

指定要與基本驗證搭配使用的使用者名稱和密碼。

"authentication":{
   "type":"Basic",
   "username":"****",
   "password":"****"
}

用戶端憑證

指定 PFX 檔案和密碼的 base64 編碼內容。

"authentication":{
   "type":"ClientCertificate",
   "pfx":"****",
   "password":"****"
}

憑證必須是 x509 憑證。若要轉換成 PFX 檔案，您可以使用您慣用的公用程式。針對 base-64 編碼，您可以使用下列 PowerShell 程式碼片段。

$fileContentBytes = get-content 'enr.dev.webactivity.pfx' -AsByteStream

[System.Convert]::ToBase64String($fileContentBytes) | Out-File ‘pfx-encoded-bytes.txt’

受控識別

指定使用資料處理站或 Synapse 工作區實例的受控識別來要求存取權杖的資源 URI。若要呼叫 Azure 資源管理 API，請使用 https://management.azure.com/ 。如需受控識別運作方式的詳細資訊，請參閱 Azure 資源的受控識別概觀頁面。

"authentication": {
	"type": "MSI",
	"resource": "https://management.azure.com/"
}

注意

如果您的資料處理站或 Synapse 工作區是使用 Git 存放庫設定的，您必須將認證儲存在 Azure 金鑰保存庫中，才能使用基本憑證或用戶端憑證驗證。服務不會將密碼儲存在 git 中。

要求承載架構

當您使用 POST/PUT 方法時，body 屬性代表傳送至端點的承載。您可以將連結服務和資料集當做承載的一部分傳遞。以下是承載的架構：

{
    "body": {
        "myMessage": "Sample",
        "datasets": [{
            "name": "MyDataset1",
            "properties": {
                ...
            }
        }],
        "linkedServices": [{
            "name": "MyStorageLinkedService1",
            "properties": {
                ...
            }
        }]
    }
}

範例

在此範例中，管線中的 Web 活動會呼叫 REST 端點。它會將 Azure SQL 連結服務和 Azure SQL 資料集傳遞至端點。 REST 端點會使用 Azure SQL 連接字串連線到邏輯 SQL Server，並傳回 SQL Server 實例的名稱。

管線定義

{
    "name": "<MyWebActivityPipeline>",
    "properties": {
        "activities": [
            {
                "name": "<MyWebActivity>",
                "type": "WebActivity",
                "typeProperties": {
                    "method": "Post",
                    "url": "@pipeline().parameters.url",
                    "headers": {
                        "Content-Type": "application/json"
                    },
                    "authentication": {
                        "type": "ClientCertificate",
                        "pfx": "*****",
                        "password": "*****"
                    },
                    "datasets": [
                        {
                            "referenceName": "MySQLDataset",
                            "type": "DatasetReference",
                            "parameters": {
                                "SqlTableName": "@pipeline().parameters.sqlTableName"
                            }
                        }
                    ],
                    "linkedServices": [
                        {
                            "referenceName": "SqlLinkedService",
                            "type": "LinkedServiceReference"
                        }
                    ]
                }
            }
        ],
        "parameters": {
            "sqlTableName": {
                "type": "String"
            },
            "url": {
                "type": "String"
            }
        }
    }
}

管線參數值

{
    "sqlTableName": "department",
    "url": "https://adftes.azurewebsites.net/api/execute/running"
}

Web 服務端點程式碼


[HttpPost]
public HttpResponseMessage Execute(JObject payload)
{
    Trace.TraceInformation("Start Execute");

    JObject result = new JObject();
    result.Add("status", "complete");

    JArray datasets = payload.GetValue("datasets") as JArray;
    result.Add("sinktable", datasets[0]["properties"]["typeProperties"]["tableName"].ToString());

    JArray linkedServices = payload.GetValue("linkedServices") as JArray;
    string connString = linkedServices[0]["properties"]["typeProperties"]["connectionString"].ToString();

    System.Data.SqlClient.SqlConnection sqlConn = new System.Data.SqlClient.SqlConnection(connString);

    result.Add("sinkServer", sqlConn.DataSource);

    Trace.TraceInformation("Stop Execute");

    return this.Request.CreateResponse(HttpStatusCode.OK, result);
}

請參閱其他支援的控制流程活動：