Azure 数据工厂中的 Webhook 活动Webhook activity in Azure Data Factory

适用于:是 Azure 数据工厂是 Azure Synapse Analytics(预览版)APPLIES TO: yesAzure Data Factory yesAzure Synapse Analytics (Preview)

Webhook 活动可通过自定义代码控制管道的执行。A webhook activity can control the execution of pipelines through your custom code. 使用 Webhook 活动,客户的代码可以调用终结点并为其传递回调 URL。With the webhook activity, customers' code can call an endpoint and pass it a callback URL. 管道运行在继续下一个活动之前,会等待系统调用回调。The pipeline run waits for the callback invocation before it proceeds to the next activity.

语法Syntax


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

Type 属性Type properties

propertiesProperty 说明Description 允许的值Allowed values 必选Required
name name Webhook 活动的名称。The name of the webhook activity. StringString Yes
type type 必须设置为“WebHook”。Must be set to "WebHook". StringString Yes
methodmethod 目标终结点的 REST API 方法。The REST API method for the target endpoint. 字符串。String. 支持的类型为“POST”。The supported type is "POST". Yes
urlurl 目标终结点和路径。The target endpoint and path. 具有字符串的 resultType 值的字符串或表达式。A string or an expression with the resultType value of a string. Yes
headersheaders 发送到请求的标头。Headers that are sent to the request. 下面是一个示例,用于在请求中设置语言和类型:"headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }Here's an example that sets the language and type on a request: "headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }. 具有字符串的 resultType 值的字符串或表达式。A string or an expression with the resultType value of a string. 是的。Yes. 需要 Content-Type 标题,如 "headers":{ "Content-Type":"application/json"}A Content-Type header like "headers":{ "Content-Type":"application/json"} is required.
bodybody 表示要发送到终结点的有效负载。Represents the payload that is sent to the endpoint. 有效的 JSON,或 resultType 值为 JSON 的表达式。Valid JSON or an expression with the resultType value of JSON. 请参阅请求有效负载架构,了解请求有效负载的架构。See Request payload schema for the schema of the request payload. Yes
身份验证authentication 用于调用该终结点的身份验证方法。The authentication method used to call the endpoint. 支持的类型为“Basic”和“ClientCertificate”。Supported types are "Basic" and "ClientCertificate". 有关详细信息,请参阅身份验证For more information, see Authentication. 如果不需要身份验证,则排除此属性。If authentication isn't required, exclude this property. 具有字符串的 resultType 值的字符串或表达式。A string or an expression with the resultType value of a string. No
timeouttimeout 活动会等待多长时间,以便系统调用 callBackUri 所指定的回调。How long the activity waits for the callback specified by callBackUri to be invoked. 默认值为 10 分钟(“00:10:00”)。The default value is 10 minutes ("00:10:00"). 值的 TimeSpan 格式为 d.hh:mm:ssValues have the TimeSpan format d.hh:mm:ss. StringString No
回调时报告状态Report status on callback 允许用户报告 Webhook 活动的失败状态。Lets a user report the failed status of a webhook activity. BooleanBoolean No

AuthenticationAuthentication

Webhook 活动支持以下身份验证类型。A webhook activity supports the following authentication types.

None

如果不需要身份验证,请勿包括 authentication 属性。If authentication isn't required, don't include the authentication property.

基本Basic

指定与基本身份验证配合使用的用户名和密码。Specify the username and password to use with basic authentication.

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

客户端证书Client certificate

指定 PFX 文件和密码的 Base64 编码内容。Specify the Base64-encoded contents of a PFX file and a password.

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

托管标识Managed identity

使用数据工厂的托管标识指定为其请求访问令牌的资源 URI。Use the data factory's managed identity to specify the resource URI for which the access token is requested. 若要调用 Azure 资源管理 API,请使用 https://management.chinacloudapi.cn/To call the Azure Resource Management API, use https://management.chinacloudapi.cn/. 有关如何托管标识工作原理的详细信息,请参阅 Azure 资源的托管标识概述For more information about how managed identities work, see the managed identities for Azure resources overview.

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

附加说明Additional notes

数据工厂在发送到 URL 终结点的正文中传递附加属性 callBackUriData Factory passes the additional property callBackUri in the body sent to the URL endpoint. 数据工厂需要在指定的超时值之前调用此 URI。Data Factory expects this URI to be invoked before the specified timeout value. 如果未调用此 URI,则活动会失败,其状态为“超时”。If the URI isn't invoked, the activity fails with the status "TimedOut".

只有当无法调用自定义终结点时,Webhook 活动才会失败。The webhook activity fails when the call to the custom endpoint fails. 任何错误消息都可以添加到回调正文,并在后续活动中使用。Any error message can be added to the callback body and used in a later activity.

对于每个 REST API 调用,如果终结点在一分钟内未响应,则客户端会超时。For every REST API call, the client times out if the endpoint doesn't respond within one minute. 此行为是标准的 HTTP 最佳做法。This behavior is standard HTTP best practice. 若要解决此问题,请实施 202 模式。To fix this problem, implement a 202 pattern. 在当前情况下,终结点返回“202 (已接受)”和客户端轮询。In the current case, the endpoint returns 202 (Accepted) and the client polls.

请求的一分钟超时与活动超时无关。The one-minute timeout on the request has nothing to do with the activity timeout. 后者用于等待 callbackUri 指定的回调。The latter is used to wait for the callback specified by callbackUri.

传递回到回调 URI 的正文必须是有效 JSON。The body passed back to the callback URI must be valid JSON. Content-Type 标头设置为 application/jsonSet the Content-Type header to application/json.

使用 Report status on callback 属性时,必须在进行回调时将以下代码添加到正文中:When you use the Report status on callback property, you must add the following code to the body when you make the 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
}

后续步骤Next steps

查看数据工厂支持的以下控制流活动:See the following control flow activities supported by Data Factory: