你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

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

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

Web 活动可用于从 Azure 数据工厂或 Synapse 管道调用自定义的 REST 终结点。 可以传递数据集和链接服务以供活动使用和访问。

注意

使用自承载集成运行时,还支持 Web 活动调用专用虚拟网络中托管的 URL。 该集成运行时应可以看到 URL 终结点。

注意

支持的最大输出响应负载大小为 4 MB。

使用 UI 创建 Web 活动

若要在管道中使用 Web 活动,请完成以下步骤:

  1. 在管道“活动”窗格中搜索“Web”,然后将 Web 活动拖动到管道画布上。

  2. 如果尚未选择画布上的新 Web 活动,请选择它及其“设置”选项卡,以编辑其详细信息。

    显示 Web 活动的 UI。

  3. 指定一个 URL,它可以是文本 URL 字符串,也可以是动态表达式、函数系统变量其他活动的输出的任意组合。 提供要与请求一起提交的其他详细信息。

  4. 将活动的输出用作任何其它活动的输入,并在目标活动中支持动态内容的任何位置引用输出。

语法

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

后续步骤

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