Azure 数据工厂和 Azure Synapse Analytics 中的 Web 活动

项目
12/29/2023

适用于： Azure 数据工厂 Azure Synapse Analytics

提示

试用 Microsoft Fabric 中的数据工厂，这是一种适用于企业的一站式分析解决方案。 Microsoft Fabric 涵盖从数据移动到数据科学、实时分析、商业智能和报告的所有内容。了解如何免费开始新的试用！

Web 活动可用于从 Azure 数据工厂或 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"
         }
      ]
   }
}

Type 属性

属性	说明	允许的值	必需
name	Web 活动的名称	String	是
type	必须设置为 WebActivity。	String	是
method	目标终结点的 REST API 方法。	字符串。支持的类型：“GET”、“POST”、“PUT”、“PATCH”、“DELETE”	是
url	目标终结点和路径	字符串（或带有 resultType 字符串的表达式）。如果活动在 1 分钟内未收到终结点的响应，则会超时并显示错误。可以通过更新 httpRequestTimeout 属性来将此响应超时增加最多 10 分钟	是
httpRequestTimeout	响应超时持续时间	hh:mm:ss，其最大值为 00:10:00。如果未显式指定，则默认值为 00:01:00	否
headers	发送到请求的标头。例如，若要在请求中设置语言和类型：`"headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }`。	字符串（或带有 resultType 字符串的表达式）	否
body	表示要发送到终结点的有效负载。	字符串（或带有 resultType 字符串的表达式）。请参阅请求有效负载架构部分中的请求有效负载架构。	对于 POST/PUT/PATCH 方法是必需的。对于 DELETE 方法是可选项。
authentication	用于调用该终结点的身份验证方法。支持的类型是“基本、客户端证书、系统分配的托管标识、用户分配的托管标识、服务主体”。有关详细信息，请参阅身份验证部分。如果不需要身份验证，则排除此属性。	字符串（或带有 resultType 字符串的表达式）	否
turnOffAsync	用于禁用对 HTTP 202 响应的响应头中的位置字段调用 HTTP GET 的选项。如果设置为 true，它将停止对响应头中给定的 http 位置调用 HTTP GET。如果设置为 false，它将继续对 http 响应头中给定的位置调用 HTTP GET。	允许的值为 false（默认）和 true 。	否
disableCertValidation	删除服务器端证书验证（除非你要连接到不使用标准 CA 证书的受信任服务器，否则不建议这样做）。	允许的值为 false（默认）和 true 。	否
datasets	传递给终结点的数据集列表。	数据集引用数组。可以是空数组。	是
linkedServices	传递给终结点的链接服务列表。	链接服务引用数组。可以是空数组。	是
connectVia	用于连接到数据存储的集成运行时。可使用 Azure Integration Runtime 或自承载集成运行时（如果数据存储位于专用网络中）。如果未指定此属性，服务会使用默认的 Azure Integration Runtime。	集成运行时引用。	否

注意

Web 活动调用的 REST 终结点必须返回 JSON 类型的响应。如果活动在 1 分钟内未收到终结点的响应，则会超时并显示错误。对于支持异步请求-答复模式的终结点，Web 活动将继续等待而不会超时（最多等待 7 天），或者等到终结点指示作业已完成为止。

下表显示了 JSON 上下文的要求：

值类型	请求正文	响应正文
JSON 对象	支持	支持
JSON 数组	已支持（目前，由于一个 bug，JSON 数组无法正常工作。正在进行修复。）	不支持
JSON 值	支持	不支持
非 JSON 类型	不支持	不支持

身份验证

下面是 Web 活动中支持的身份验证类型。

无

如果不需要身份验证，请排除“身份验证”属性。

基本

指定用户名和密码以用于基本身份验证。

"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.chinacloudapi.cn/。有关如何托管标识工作原理的详细信息，请参阅 Azure 资源概述页面的托管标识。

"authentication": {
	"type": "MSI",
	"resource": "https://management.chinacloudapi.cn/"
}

请求有效负载架构

当使用 POST/PUT 方法时，正文属性表示发送到终结点的有效负载。可以将链接服务和数据集作为有效负载的一部分进行传递。下面是有效负载的架构：

{
    "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.chinacloudsites.cn/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);
}

参阅支持的其他控制流活动：