Azure Data Factory中的 Webhook 活动

适用于： Azure Data Factory Azure Synapse Analytics

Webhook 活动可通过自定义代码控制管道的执行。使用 Webhook 活动，代码可以调用终结点并向其传递回叫 URL。管道运行会在收到回调调用后，才继续进行下一个活动。

重要

WebHook 活动现在允许你将错误状态和自定义消息反馈给活动和管道。将“reportStatusOnCallBack”设置为 true，并在回调有效负载中包含“StatusCode”和“Error”。有关详细信息，请参阅其他说明部分。

使用 UI 创建 Webhook 活动

若要在管道中使用 Webhook 活动，请完成以下步骤：

在管道“活动”窗格中搜索Webhook，然后将“Webhook”活动拖动到管道画布上。
如果尚未选择画布上的新 Webhook 活动，请选择其“设置”选项卡，以编辑其详细信息。
指定 Webhook 的 URL，它可以是文本 URL 字符串，也可以是动态表达式、函数、系统变量或其他活动的输出的任意组合。提供要与请求一起提交的其他详细信息。
将活动的输出用作任何其它活动的输入，并在目标活动中支持动态内容的任何位置引用输出。

语法


{
    "name": "MyWebHookActivity",
    "type": "WebHook",
    "typeProperties": {
        "method": "POST",
        "url": "<URLEndpoint>",
        "headers": {
            "Content-Type": "application/json"
        },
        "body": {
            "key": "value"
        },
        "timeout": "00:10:00",
        "reportStatusOnCallBack": false,
        "authentication": {
            "type": "ClientCertificate",
            "pfx": "****",
            "password": "****"
        }
    }
}

类型属性

属性	说明	允许的值	必需
name	Webhook 活动的名称。	字符串	是
类型	必须设置为“WebHook”。	字符串	是
方法	目标终结点的 REST API 方法。	字符串。支持的类型为“POST”。	是
url	目标终结点和路径。	一个字符串或表达式，其 resultType 值为字符串。	是
标题	发送到请求的标头。下面是一个示例，用于在请求中设置语言和类型：`"headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }`。	一个字符串或表达式，其 resultType 值为字符串。	是的。需要 `Content-Type` 标题，如 `"headers":{ "Content-Type":"application/json"}`。
正文	表示要发送到终结点的有效负载。	有效的 JSON，或 resultType 值为 JSON 的表达式。请参阅请求有效负载架构，了解请求有效负载的架构。	是
身份验证	用于调用终结点的身份验证方法。支持的类型为“Basic”和“ClientCertificate”。有关详细信息，请参阅身份验证。如果不需要身份验证，则排除此属性。	一个字符串或表达式，其 resultType 值为字符串。	否
超时	活动会等待多长时间，以便系统调用 callBackUri 所指定的回调。默认值为 10 分钟（“00:10:00”）。值的 TimeSpan 格式为 d.hh:mm:ss。	字符串	否
回调时报告状态	允许用户报告 Webhook 活动的失败状态。	布尔	否

身份验证

Webhook 活动支持以下身份验证类型。

无

如果不需要身份验证，请勿包括 authentication 属性。

基本

指定与基本身份验证配合使用的用户名和密码。

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

客户端证书

指定 PFX 文件的 Base64 编码内容以及密码。

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

托管身份

使用数据工厂或 Synapse 工作区的托管标识来指定为其请求访问令牌的资源 URI。若要调用Azure资源管理 API，请使用 https://management.chinacloudapi.cn/。有关托管标识工作原理的详细信息，请参阅 Azure 资源的托管标识概述。

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

附加说明

此服务在发送到 URL 终结点的正文中传递附加属性 callBackUri。该服务希望在指定的超时值之前调用此 URI。如果未调用此 URI，则活动会失败，其状态为“超时”。

只有当无法调用自定义终结点时，Webhook 活动才会失败。任何错误消息都可以添加到回调正文，并在后续活动中使用。

对于每个 REST API 调用，如果端点在一分钟内未响应，客户端将会超时。此行为是标准的 HTTP 最佳做法。若要解决此问题，请实施 202 模式。在当前情况下，端点返回“202 (已接受)”，并且客户端进行轮询。

请求的一分钟超时与活动超时无关。后者用于等待 callbackUri 指定的回调。

回传到回调 URI 的正文必须是有效的 JSON。将 Content-Type 标头设置为 application/json。

使用 Report status on callback 属性时，必须在进行回调时将以下代码添加到正文中：

{
    "Output": {
        // output object is used in activity output
        "testProp": "testPropValue"
    },
    "Error": {
        // Optional, set it when you want to fail the activity
        "ErrorCode": "testErrorCode",
        "Message": "error message to show in activity error"
    },
    "StatusCode": "403" // when status code is >=400, activity is marked as failed
}

请参阅以下受支持的控制流活动：

Last updated on 2026-03-10

通过