Webhook 触发器

5 分钟

Webhooks 是以更为热门的基于 HTTP 的方式实现更为通用的发布者-订阅者通知模式。它们会在系统中（发布者）出现特定事件时，以某种方式向外部服务（订阅者）发布通知。

Power Automate和 Azure 逻辑应用支持创建者将 Webhooks 用作触发器。在本场景下，触发器将扮演代表创建者注册和取消注册 Webhooks 的订阅者的角色。当创建或更新云端流或逻辑应用工作流中的某个步骤时，便会进行注册。删除步骤时，平台会取消注册 Webhook。

以下屏幕截图显示了订阅者与发布者之间的一个交互示例。

下表概述了双方责任。

发布者（自定义连接器 OpenAPI）	订阅者（Power Automate/逻辑应用）
提供订阅注册端点。	在流中创建或更新触发器时调用订阅注册端点。
指定通知合同，即每个通知将会传递什么对象。创建 Webhook 时，必须在 201 响应中添加位置 HTTP 标题。	提供将会接受通知消息的自动生成端点的 URL。
留存包含订阅者及其通知端点的登记簿。	接收并存储将用于取消注册 Webhook 的位置信息。
向每个注册端点发布一个 POST 请求，并在消息正文中传递相关数据。	接收通知，对照由自定义连接器定义的架构进行验证，然后触发自动化。
取消注册/删除端点，以响应 DELETE 消息。	删除触发器步骤时，发送 DELETE 消息以取消注册 Webhook。

Webhooks 仅提供通知机制，不支持操纵数据。通常，Webhook 实现会辅以一个或多个旨在支持检索和操纵数据或对象的操作。

API 要求

要提供自定义连接器所需的 Webhook 支持，API 实现必须提供以下参数：

接受注册消息并返回位置信息的端点
随通知消息发送的消息正文的定义
接受 DELETE 消息以删除 Webhook 注册的端点

通常，API 实现会保留活跃订阅者的内部列表，每个订阅者均通过唯一 URL 进行标识。要将本 URL 返回至订阅者，需要成功创建 Webhook 才能返回 HTTP 201 响应并添加位置 HTTP 标头。订阅者稍后将使用本位置的值删除 Webhook 注册。

创建 Webhook 触发器

按照 Webbook 的要求，自定义连接器会使用 OpenAPI 来描述发布者 API 实现。要在自定义连接器中定义 Webhook 触发器，您需要在 OpenAPI 定义中添加三个基本部分：

描述 Webhook 注册的 POST 消息
Webhook 响应的内容定义
描述 Webhook 拆分流程的 DELETE 消息

注册消息

触发器定义必须包含用于注册 Webhook 的 POST 方法。其定义与操作类似。

Microsoft Power Platform 所使用的 OpenAPI 说明版本无法区分操作和触发器。该自定义连接器定义使用了 x-ms-trigger 自定义扩展来声明触发器。

paths:
  /webhooks:
    post:
      operationId: OrderCreated
      x-ms-trigger: single

x-ms-trigger 扩展的存在表明该方法为触发器，而非操作。使用向导创建触发器时，会自动添加本扩展。然而，如果是从外部 OpenAPI 定义创建自定义连接器，则导入程序总是会创建操作。这种情况下，您需要使用向导重新创建触发器，然后删除相应的操作定义。

x-ms-trigger 扩展的可能值有单个或批，用于区分单个对象和组合响应。当 Webhook 针对每项更改逐一发送通知时，会发送单个对象。本方法在 Webhook 中最为常见。如果在单个通知中整合多项更改，则会发送组合对象。本方法常见于轮询触发器，本模块稍后将会讨论。

Webhook 响应

发生事件时，自定义连接器定义可以描述从服务中传入的 Webhook 响应的内容。虽然非必需，但本定义确定了设计时在动态内容列表中可供创建者使用的动态值。

注意

本响应不属于创建和注册 Webhook 的请求。发生事件时，本数据将由您的服务发送。

自定义 x-ms-notification-content 属性是 OpenAPI 中使用的，用于定义 Webhook 响应架构的另一项扩展。

paths:
  /webhooks:
    x-ms-notification-content:
      description: Order
      schema:
        type: object
        properties:
          id: {type: integer, format: int32, description: id}
          order_key: {type: string, description: order_key}
          status: {type: string, description: status}
          currency: {type: string, description: currency}
          date_created: {type: string, description: date_created}
          total: {type: number, description: total, format: decimal}

提示

Webhook 响应定义无需包含完整的响应内容，只需包含您想要在设计时间通过动态内容列表向流创建者公开的部分即可。

通过 Webhook 响应发送的数据不需要，可能也不会包含来自基对象的所有属性。这种情况下，您会希望在自定义连接器中创建其他操作来检索信息。例如，Web 商店可能只会发送带有“新订单已创建”通知的新订单标识符。然后，自定义连接器可以定义一个操作，例如“获取订单详细信息”，以接收订单标识符并返回与订单相关的扩展信息。

反之亦然。 Webhook 响应可能会提供正常情况下不需要的冗余信息。您只需要描述您想要在 Power Automate 或逻辑应用创建者界面显示的数据。如果创建者需要访问通知中发送的更多数据，可以使用 JSON 函数直接从收到的消息中提取这些属性。

删除消息

对于要删除 Webhook 的 Power Automate 或逻辑应用，API 必须在响应中添加创建 Webhook 时的位置 HTTP 标头。

重要提示

您必须在内部操作中定义删除 Webhook 请求的路径。本操作会向位置标头中指定的 URL 发送 DELETE 请求。

如果未定义本操作，或者 API 中不含位置标头，则将创建但不会删除 Webhook，由本可能在运行时导致 API 实现出现问题。

Webhooks 实现提供了灵活机制，该机制可在自定义连接器中提供触发支持。不过，并非所有 API 都支持 Webhook 集成。轮询实现提供了其他方式在自定义连接器中创建触发器。

继续