Webhook 是简单的 HTTP 回调,用于在 Web 服务中发生事件时提供事件通知。 在Azure 逻辑应用和Power Automate中,可以使用 Webhook 作为触发器。 逻辑应用或流侦听此触发器,只要触发器触发即执行操作。 本教程演示如何通过使用 OpenAPI 规范定义的自定义连接器将 Webhook 用作触发器。
备注
本文使用 GitHub 作为可以通过 Webhook 发送通知的服务的示例,但你可以将此处演示的技术扩展到允许 Webhook 的任何服务。
先决条件
- 以下订阅之一:
- Azure,如果您使用 Logic Apps
- Power Automate
- 构建 逻辑应用 或 云流以及 从 OpenAPI 定义创建自定义连接器的基本经验。
- 如果使用的是逻辑应用,请先创建 Azure 逻辑应用自定义连接器。
- 基本了解 Webhook。
- 对 OpenAPI 规范(以前称为 Swagger)的基本了解。
- GitHub 帐户。
- 本教程的示例 OpenAPI 定义。 如果尚未安装,请下载它以在后续步骤中使用。 否则,需要为 Webhook 创建自定义 OpenAPI 定义。
在 GitHub 中启用身份验证
向逻辑应用或Power Automate发送 Webhook 请求的 Web 服务 API 通常使用某种形式的身份验证,GitHub也不例外。 GitHub支持多种身份验证类型。 本教程使用GitHub精细的个人访问令牌。
如果尚未登录,请转到GitHub登录。
在右上角,选择个人资料图片,然后在菜单中选择“设置”。
在左侧菜单中,选择 “开发人员设置”。
在个人访问令牌下,选择细粒度令牌。
选择“ 生成新令牌 ”按钮,然后确认密码(如果已请求)。
输入令牌名称和说明。
在 “过期”下,选择令牌的到期日期。
在 “存储库访问权限”下, 选择“仅选择存储库”,然后选择要授予访问权限的存储库。
在 “权限”下,选择 “添加权限”>Webhooks>读取和写入。
选择“ 生成令牌 ”按钮。
记下你的新令牌。 稍后在将 Webhook 连接器添加为触发器时,需要使用此令牌。
重要
无法再次访问此令牌。 将它复制并粘贴到某个位置,以便稍后在本教程中使用。
在 OpenAPI 定义中定义 Webhook
你在 Logic Apps 和 Power Automate 中将 Webhook 作为自定义连接器的一部分来实现。 若要创建连接器,需要提供定义 Webhook 形状的 OpenAPI 定义。 本教程使用一个已下载的 GitHub Webhook 示例 OpenAPI 定义。
如果要创建触发器,但没有 OpenAPI 定义,请使用自定义连接器向导中的 触发器 UI 来定义 Webhook 触发器。
示例 OpenAPI 定义包含使 Webhook 正常工作至关重要的三个部分:
- 创建 Webhook
- 定义来自 Web 服务 API 的传入挂钩请求(在本教程示例中,GitHub)
- 删除 Webhook
连接器使用此 OpenAPI 定义来了解如何为GitHub存储库创建、接收和删除 Webhook。
创建 Webhook
连接器使用 Web 服务 API(在本例中,GitHub REST API)通过向 Web 服务的相应 Webhook 创建终结点(在GitHub的情况下)发送 HTTP POST 请求,在 Web 服务/repos/{owner}/{repo}/hooks端创建 Webhook。
使用连接器创建新的逻辑应用或流时,连接器会将 POST 请求发送到 Web 服务的 Create Webhook 终结点,如连接器的 OpenAPI 定义中定义。 如果修改逻辑应用或流触发器,它还会向此 URL 发送 POST 请求。 在以下示例 OpenAPI 路径配置中,post该属性包含要发送到 GitHub REST API 的创建 Webhook 请求的架构。
"/repos/{owner}/{repo}/hooks": {
"x-ms-notification-content": {
"description": "Details for Webhook",
"schema": {
"$ref": "#/definitions/WebhookPushResponse"
}
},
"post": {
"description": "Creates a GitHub webhook",
"summary": "Triggers when a PUSH event occurs",
"operationId": "webhook-trigger",
"x-ms-trigger": "single",
"parameters": [
{
"name": "owner",
"in": "path",
"description": "Name of the owner of targeted repository",
"required": true,
"type": "string"
},
{
"name": "repo",
"in": "path",
"description": "Name of the repository",
"required": true,
"type": "string"
},
{
"name": "Request body of webhook",
"in": "body",
"description": "This is the request body of the Webhook",
"schema": {
"$ref": "#/definitions/WebhookRequestBody"
}
}
],
"responses": {
"201": {
"description": "Created",
"schema": {
"$ref": "#/definitions/WebhookCreationResponse"
}
}
}
}
},
重要
"x-ms-trigger": "single" 属性是一种架构扩展,用于告知 Logic Apps 和 Power Automate 在设计器的可用触发器列表中显示此 webhook。 请务必将其包含在内。
定义来自 API 的传入挂钩请求
在自定义x-ms-notification-content属性中定义传入挂钩请求(从GitHub到逻辑应用或Power Automate的通知)的形状,如前面的示例所示。 该请求无需包含请求的全部内容,只需包含你想在逻辑应用或流程中使用的部分。
删除 Webhook
在 OpenAPI 定义中包含有关如何删除 Webhook 的定义。 如果你更新了触发器,或者删除了逻辑应用或流,Logic Apps 和 Power Automate 会尝试删除现有的 webhook。
"/repos/{owner}/{repo}/hooks/{hook_Id}": {
"delete": {
"description": "Deletes a Github webhook",
"operationId": "DeleteTrigger",
"parameters": [
{
"name": "owner",
"in": "path",
"description": "Name of the owner of targeted repository",
"required": true,
"type": "string"
},
{
"name": "repo",
"in": "path",
"description": "Name of the repository",
"required": true,
"type": "string"
},
{
"name": "hook_Id",
"in": "path",
"description": "ID of the webhook being deleted",
"required": true,
"type": "string"
}
]
}
},
删除 Webhook 调用中不包含任何请求头。 删除 Webhook 调用使用与连接器相同的连接。
重要
若要让 Logic Apps 或 Power Automate 能够删除 webhook,Web 服务 API 在创建 webhook 时返回的 201 响应中必须包含 Location HTTP 标头。 标头 Location 应包含与 HTTP DELETE 方法一起使用的 Webhook 的路径。 例如,LocationGitHub响应中包含的标头遵循以下格式: https://api.github.com/repos/<user name>/<repo name>/hooks/<hook ID>
导入 OpenAPI 定义
首先为逻辑应用或 Power Automate 导入 OpenAPI 定义。
为逻辑应用导入 OpenAPI 定义
转到 Azure 门户,打开前面在创建 Azure 逻辑应用自定义连接器中创建的逻辑应用连接器。
在连接器的菜单中,选择逻辑应用连接器,然后选择编辑。
在 “常规”下,选择“ 上传 OpenAPI 文件”,然后转到下载的示例 OpenAPI 文件。
为 Power Automate 导入 OpenAPI 定义
在右上角,选择齿轮图标,然后选择 “自定义连接器”。
选择“ 创建自定义连接器”,然后选择“ 导入 Postman 集合”。
输入自定义连接器的名称,转到下载的示例 OpenAPI 文件,然后选择 “连接”。
参数 值 自定义连接器标题 “GitHubDemo”
完成自定义连接器的创建
在 “常规 ”页上,选择“ 继续”。
在安全性页的身份验证类型下,选择基本身份验证。
在基本身份验证部分中,为标签字段输入文本用户名和密码。 在逻辑应用或流中使用触发器时,将显示这些标签。
在向导顶部,确保名称设置为“GitHubDemo”,然后选择“ 创建连接器”。
您现在已准备好在逻辑应用或流中使用触发器了,或者您可以阅读有关如何从 UI 创建触发器的信息。
在界面中创建Webhook触发器
在本部分中,你将了解如何在 UI 中创建触发器,而无需在 OpenAPI 定义中具有任何触发器定义。 从基准 OpenAPI 定义开始,或在自定义连接器向导中从头开始。
在常规页面上,请确保指定描述和 URL。
参数 值 说明 GitHub 是一个社交化源代码托管平台。 URL “api.github.com” 在安全性页上,配置基本身份验证(与上一节一样)。
在 “定义 ”页上,选择 “新建触发器”,并填写触发器的说明。 在此示例中,你将创建一个触发器,一向存储库发出拉取请求就会触发该触发器。
参数 值 摘要 当在选定的存储库中创建拉取请求时触发 说明 当向所选存储库发出拉取请求时触发 操作 ID “webhook-PR-trigger” 可见性 “无”(请参见下方了解更多信息) 触发器类型 “Webhook” 逻辑应用或流中的操作和参数的可见性属性包含以下选项:
- 无:通常在逻辑应用或流中显示
- 高级:在其他菜单下隐藏
- 内部:向用户隐藏
- 重要:始终先向用户显示
请求区域基于对操作的 HTTP 请求显示信息。 选择从示例导入。
定义 Webhook 触发器的请求,然后选择“ 导入”。 我们提供了一个示例供你导入(在下一部分中)。 有关详细信息,请参阅 GitHub API 参考。 逻辑应用和 Power Automate 会自动添加标准和
content-type安全标头,因此无需在从示例导入时定义这些标头。
参数 值 动词 "POST" URL “https://api.github.com/repos/{owner}/{repo}/hooks" 正文 请参阅以下内容 { "name": "web", "active": true, "events": [ "pull_request" ], "config": { "url": "http://example.com/webhook" } }响应区域基于对操作的 HTTP 响应显示信息。 选择添加默认响应。
定义 Webhook 触发器的响应,然后选择“ 导入”。 同样,我们为您提供了一个用于导入的示例。 有关详细信息,请参阅 GitHub API 参考。
{ "action": "opened", "number": 1, "pull_request": { "html_url": "https://github.com/baxterthehacker/public-repo/pull/1", "state": "open", "locked": false, "title": "Update the README with new information", "user": { "login": "baxterthehacker", "type": "User" } } }在触发器配置区域,选择应从 GitHub 接收回拨 URL 值的参数。 此参数是
url对象中的config属性。
在向导顶部输入名称,然后选择 “创建连接器”。
使用 Webhook 作为触发器
完成所有配置后,请通过自定义连接器在逻辑应用或流中使用 webhook。 接下来,创建一个流程,使其在你的 GitHub 仓库每次收到 git push 时都发送一封电子邮件。
在 https://make.powerautomate.com/页面顶部,选择 “我的流”。
选择“从空白创建”。
在适用于 Power Automate 的设计器中,搜索以前注册的自定义连接器。
选择列表中的项以将其用作触发器。
由于这是你第一次使用此自定义连接器,因此请连接到它。 输入连接信息,然后选择“ 创建”。
参数 值 连接名称 描述性名称 用户名 您的 GitHub 用户名 密码 您以前创建的个人访问令牌 输入有关要监视的存储库的详细信息。 您可以识别 OpenAPI 文件中 WebhookRequestBody 对象提供的字段。
参数 值 负责人 要监视的存储库的所有者 存储库 要监视的存储库 重要
使用你的账户有权访问的存储库。 执行此操作的最简单方法是使用自己的存储库。
选择新建步骤>和添加操作。
搜索并选择“ 发送电子邮件”(V2) 操作。
使用动态内容对话框中的值在 “正文 ”字段和其他字段中输入文本。 值来自 OpenAPI 文件中的 WebhookPushResponse 对象。
在页面顶部,为流提供名称并单击选择创建流。
验证和故障排除
若要验证是否已正确设置所有内容,请选择 “我的流”,然后选择新流旁边的 信息图标 以查看运行历史记录:
- 你应该已经能看到至少一条因创建 webhook 而产生的 成功 运行记录。 此运行表示 webhook 已成功在GitHub端创建。
- 如果运行失败,请查看运行详细信息以查看失败的原因。 如果失败是由
404 Not Found响应导致的,则你的 GitHub 账户很可能没有在所用仓库上创建 webhook 的相应权限。
摘要
如果已正确配置所有内容,每当所选GitHub存储库发生 git 推送时,你都会收到Power Automate移动应用中的推送通知。 使用上述过程,可以将任何支持 Webhook 的服务用作流中的触发器。
后续步骤
提供反馈
我们非常感谢大家提出有关连接器平台问题或新功能想法的反馈。 要提供反馈,请转到提交问题或获取连接器帮助,然后选择反馈类型。