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

發行項
04/26/2024

適用於：Azure Data Factory Azure Synapse Analytics

提示

試用 Microsoft Fabric 中的 Data Factory，這是適用於企業的全方位分析解決方案。 Microsoft Fabric 涵蓋從資料移動到資料科學、即時分析、商業智慧和報告的所有項目。了解如何免費開始新的試用！

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

注意

Web 活動也支援用於叫用裝載於私人虛擬網路的 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"、"DELETE"	Yes
URL	目標端點和路徑	字串 (或含有字串之 resultType 的運算式)。如果活動未在 1 分鐘內收到來自端點的回應，就會發生逾時並出現錯誤。您可以更新 httpRequestTimeout 屬性，將此回應逾時時間最多提高至 10 分鐘。	Yes
httpRequestTimeout	回應逾時持續時間	hh:mm:ss，最大值為 00:10:00。如未明確指定，預設值為 00:01:00	No
標題	傳送至要求的標頭。例如，若要對要求設定語言和類型︰`"headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }`。	字串 (或含有字串之 resultType 的運算式)	No
本文	代表傳送至端點的承載。	字串 (或含有字串之 resultType 的運算式)。請在要求乘載結構描述一節中查看要求乘載的結構描述。	POST/PUT/PATCH 方法的必要條件。對於 DELETE 方法是選用的。
驗證 (authentication)	呼叫端點所使用的驗證方法。支援的類型為「基本、用戶端憑證、系統指派的受控識別、使用者指派的受控識別、服務主體」。如需詳細資訊，請參閱驗證一節。如果不需要驗證，請排除這個屬性。	字串 (或含有字串之 resultType 的運算式)	No
turnOffAsync	選擇是否停用在 HTTP 202 回應之回應標頭中的位置欄位叫用 HTTP GET。如果設為 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 陣列因為錯誤的結果無法運作。正在執行修正。)	不支援
JSON 值	支援	不支援
非 JSON 型別	不支援	不支援

驗證

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

無

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

基本

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

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

用戶端憑證

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

"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 Key Vault，以使用基本或用戶端憑證驗證。服務無法將密碼儲存在 Git。

要求承載結構描述

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

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

範例

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

管線定義

{
    "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);
}

查看其他支援的控制流程活動：