将 webhook 用作 Azure 逻辑应用和 Power Automate 的触发器

Webhook 是简单的 HTTP 回调,用于在 Web 服务中发生事件时提供事件通知。 在Azure 逻辑应用和Power Automate中,可以使用 Webhook 作为触发器。 逻辑应用或流侦听此触发器,只要触发器触发即执行操作。 本教程演示如何通过使用 OpenAPI 规范定义的自定义连接器将 Webhook 用作触发器。

备注

本文使用 GitHub 作为可以通过 Webhook 发送通知的服务的示例,但你可以将此处演示的技术扩展到允许 Webhook 的任何服务。

先决条件

在 GitHub 中启用身份验证

向逻辑应用或Power Automate发送 Webhook 请求的 Web 服务 API 通常使用某种形式的身份验证,GitHub也不例外。 GitHub支持多种身份验证类型。 本教程使用GitHub精细的个人访问令牌。

  1. 如果尚未登录,请转到GitHub登录。

  2. 在右上角,选择个人资料图片,然后在菜单中选择“设置”。

  3. 在左侧菜单中,选择 “开发人员设置”。

  4. 在个人访问令牌下,选择细粒度令牌。

  5. 选择“ 生成新令牌 ”按钮,然后确认密码(如果已请求)。

  6. 输入令牌名称和说明。

  7. 在 “过期”下,选择令牌的到期日期。

  8. 在 “存储库访问权限”下, 选择“仅选择存储库”,然后选择要授予访问权限的存储库。

  9. 在 “权限”下,选择 “添加权限”>Webhooks>读取和写入。

  10. 选择“ 生成令牌 ”按钮。

  11. 记下你的新令牌。 稍后在将 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 定义

  1. 转到 Azure 门户,打开前面在创建 Azure 逻辑应用自定义连接器中创建的逻辑应用连接器。

  2. 在连接器的菜单中,选择逻辑应用连接器,然后选择编辑。

    逻辑应用连接器的“编辑”选项的屏幕截图。

  3. 在 “常规”下,选择“ 上传 OpenAPI 文件”,然后转到下载的示例 OpenAPI 文件。

    “上传 OpenAPI 文件”选项的屏幕截图。

为 Power Automate 导入 OpenAPI 定义

  1. 转到 https://make.powerautomate.com/ 。

  2. 在右上角,选择齿轮图标,然后选择 “自定义连接器”。

    带有“自定义连接器”选项的齿轮图标菜单的屏幕截图。

  3. 选择“ 创建自定义连接器”,然后选择“ 导入 Postman 集合”。

    “创建自定义连接器”菜单的屏幕截图,其中包含导入选项。

  4. 输入自定义连接器的名称,转到下载的示例 OpenAPI 文件,然后选择 “连接”。

    用于输入自定义连接器名称的字段的屏幕截图。

    参数 值
    自定义连接器标题 “GitHubDemo”

完成自定义连接器的创建

  1. 在 “常规 ”页上,选择“ 继续”。

  2. 在安全性页的身份验证类型下,选择基本身份验证。

  3. 在基本身份验证部分中,为标签字段输入文本用户名和密码。 在逻辑应用或流中使用触发器时,将显示这些标签。

    “基本身份验证标签”字段的屏幕截图。

  4. 在向导顶部,确保名称设置为“GitHubDemo”,然后选择“ 创建连接器”。

您现在已准备好在逻辑应用或流中使用触发器了,或者您可以阅读有关如何从 UI 创建触发器的信息。

在界面中创建Webhook触发器

在本部分中,你将了解如何在 UI 中创建触发器,而无需在 OpenAPI 定义中具有任何触发器定义。 从基准 OpenAPI 定义开始,或在自定义连接器向导中从头开始。

  1. 在常规页面上,请确保指定描述和 URL。

    参数 值
    说明 GitHub 是一个社交化源代码托管平台。
    URL “api.github.com”
  2. 在安全性页上,配置基本身份验证(与上一节一样)。

  3. 在 “定义 ”页上,选择 “新建触发器”,并填写触发器的说明。 在此示例中,你将创建一个触发器,一向存储库发出拉取请求就会触发该触发器。

    新触发器常规信息字段的屏幕截图。

    参数 值
    摘要 当在选定的存储库中创建拉取请求时触发
    说明 当向所选存储库发出拉取请求时触发
    操作 ID “webhook-PR-trigger”
    可见性 “无”(请参见下方了解更多信息)
    触发器类型 “Webhook”

    逻辑应用或流中的操作和参数的可见性属性包含以下选项:

    • 无:通常在逻辑应用或流中显示
    • 高级:在其他菜单下隐藏
    • 内部:向用户隐藏
    • 重要:始终先向用户显示
  4. 请求区域基于对操作的 HTTP 请求显示信息。 选择从示例导入。

    “定义”页的屏幕截图,其中包含“从示例导入”选项。

  5. 定义 Webhook 触发器的请求,然后选择“ 导入”。 我们提供了一个示例供你导入(在下一部分中)。 有关详细信息,请参阅 GitHub API 参考。 逻辑应用和 Power Automate 会自动添加标准和 content-type 安全标头,因此无需在从示例导入时定义这些标头。

    Webhook 触发器的请求导入对话框的屏幕截图。

    参数 值
    动词 "POST"
    URL “https://api.github.com/repos/{owner}/{repo}/hooks"
    正文 请参阅以下内容
    {
      "name": "web",
      "active": true,
      "events": [
        "pull_request"
      ],
      "config": {
        "url": "http://example.com/webhook"
      }
    }
    
  6. 响应区域基于对操作的 HTTP 响应显示信息。 选择添加默认响应。

    “定义”页“响应”区域的屏幕截图,其中显示了“添加默认响应”选项。

  7. 定义 Webhook 触发器的响应,然后选择“ 导入”。 同样,我们为您提供了一个用于导入的示例。 有关详细信息,请参阅 GitHub API 参考。

    Webhook 触发器的响应导入对话框的屏幕截图。

    {
      "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"
        }
      }
    }
    
  8. 在触发器配置区域,选择应从 GitHub 接收回拨 URL 值的参数。 此参数是 url 对象中的 config 属性。

    “触发器配置”区域的屏幕截图,其中选择了回调 URL 参数。

  9. 在向导顶部输入名称,然后选择 “创建连接器”。

使用 Webhook 作为触发器

完成所有配置后,请通过自定义连接器在逻辑应用或流中使用 webhook。 接下来,创建一个流程,使其在你的 GitHub 仓库每次收到 git push 时都发送一封电子邮件。

  1. 在 https://make.powerautomate.com/页面顶部,选择 “我的流”。

  2. 选择“从空白创建”。

    “搜索数百个连接器和触发器”选项的屏幕截图。

  3. 在适用于 Power Automate 的设计器中,搜索以前注册的自定义连接器。

    在Power Automate设计器中搜索自定义连接器触发器的屏幕截图。

  4. 选择列表中的项以将其用作触发器。

  5. 由于这是你第一次使用此自定义连接器,因此请连接到它。 输入连接信息,然后选择“ 创建”。

    新连接信息字段的屏幕截图。

    参数 值
    连接名称 描述性名称
    用户名 您的 GitHub 用户名
    密码 您以前创建的个人访问令牌
  6. 输入有关要监视的存储库的详细信息。 您可以识别 OpenAPI 文件中 WebhookRequestBody 对象提供的字段。

    触发器中存储库所有者和名称字段的屏幕截图。

    参数 值
    负责人 要监视的存储库的所有者
    存储库 要监视的存储库

    重要

    使用你的账户有权访问的存储库。 执行此操作的最简单方法是使用自己的存储库。

  7. 选择新建步骤>和添加操作。

  8. 搜索并选择“ 发送电子邮件”(V2) 操作。

  9. 使用动态内容对话框中的值在 “正文 ”字段和其他字段中输入文本。 值来自 OpenAPI 文件中的 WebhookPushResponse 对象。

  10. 在页面顶部,为流提供名称并单击选择创建流。

    流名称字段和“创建流”按钮的屏幕截图。

验证和故障排除

若要验证是否已正确设置所有内容,请选择 “我的流”,然后选择新流旁边的 信息图标 以查看运行历史记录:

  • 你应该已经能看到至少一条因创建 webhook 而产生的 成功 运行记录。 此运行表示 webhook 已成功在GitHub端创建。
  • 如果运行失败,请查看运行详细信息以查看失败的原因。 如果失败是由 404 Not Found 响应导致的,则你的 GitHub 账户很可能没有在所用仓库上创建 webhook 的相应权限。

摘要

如果已正确配置所有内容,每当所选GitHub存储库发生 git 推送时,你都会收到Power Automate移动应用中的推送通知。 使用上述过程,可以将任何支持 Webhook 的服务用作流中的触发器。

后续步骤

提供反馈

我们非常感谢大家提出有关连接器平台问题或新功能想法的反馈。 要提供反馈,请转到提交问题或获取连接器帮助,然后选择反馈类型。