使用 Webhook 发布 Microsoft Dataverse 事件
将事件从 Microsoft Dataverse 发布到外部服务的另一种方法是注册 Webhook。 Webhook 是一种基于 HTTP 的机制,用于将事件发布到您选择的任何基于 Web API 的服务。 本方法允许您编写自定义代码,该代码作为点到点集成托管在外部服务上。
Webhook 与 Azure 服务总线
当考虑集成机制时,您有一些可用选项。 在选择给定方法时,考虑各种元素很重要。
在以下情况下,考虑使用 Azure 服务总线:
需要大规模异步处理/排队。
可能需要多个订阅者才能使用给定的 Dataverse 事件。
您希望在一个集中位置管理集成体系结构。
在以下情况下,考虑使用 Webhook:
作为流程的一部分,需要针对外部系统进行同步处理(Dataverse 仅支持针对服务总线终结点进行异步处理)。
您正在执行的外部操作需要立即进行。
除非外部服务成功处理 Webhook 有效负载,否则您希望整个交易失败。
要用于集成目的的第三方 Web API 终结点已存在。
共享访问签名 (SAS) 身份验证不是首选的和/或可行的(Webhook 支持通过身份验证标头和查询字符串参数键进行身份验证)。
Webhook 身份验证选项
下表描述了可用于使用给定终结点中的 Webhook 消息的三个身份验证选项。
类型 | 描述 |
---|---|
HttpHeader | 在 HTTP 请求的标头中包括一个或多个键值对。 示例:Key1: Value1, Key2: Value2 |
WebhookKey | 包括使用代码作为键的查询字符串和终结点所需的值。 当使用 Plug-in Registration Tool 注册 Webhook 时,仅输入值。 示例:?code=00000000-0000-0000-0000-000000000001 |
HttpQueryString | 包括作为查询字符串参数的一个或多个键值对。 示例:?Key1=Value1&Key2=Value2 |
Webhook HTTP 标头
下表显示作为 Webhook 调用的一部分传递到您的服务的 HTTP 标头。 如果您要编写新的 Webhook 处理器,可以使用这些标头作为处理方法的一部分。
键 | 值描述 |
---|---|
x-request-id | 请求的唯一标识符 |
x-ms-dynamics-organization | 发送请求的租户的名称 |
x-ms-dynamics-entity-name | 传入执行上下文数据的实体的逻辑名称 |
x-ms-dynamics-request-name | 已为其注册 Webhook 步骤的事件的名称 |
x-ms-correlation-request-id | 用于跟踪任何类型的扩展的唯一标识符。 本属性由平台用于无限循环预防。 在大多数情况下,可以忽略本属性。 当您处理技术支持时可以使用本值,因为它可用于查询遥测以了解整个操作期间发生的情况。 |
x-ms-dynamics-msg-size-exceeded | 仅当 HTTP 有效负载大小超过 256 KB 时发送 |
注册 Webhook 终结点
Webhook 终结点注册的执行方式与服务终结点注册类似,都是使用 Plug-in Registration Tool。
在插件注册工具中,您可以通过在注册菜单选项下选择注册新 Web Hook 来注册新的 Webhook。
显示以下 WebHook 注册对话框,您可以在其中配置终结点的 URL 以及任何身份验证选项。
使用 HTTPHeader 身份验证注册
如果选择 HttpHeader 身份验证,屏幕会提示您添加键和值,它们将作为 HTTP 请求的一部分传递。 通常,键和值可能包括 OAuth 持有者令牌或其他各种身份验证格式。
使用 WebhookKey 身份验证注册
如果 WebhookKey 指定为身份验证方法,查询字符串将采用格式 ?code=[web hook key]
传递到具有给定键的 URL。 当您调用 Azure Functions 时,本方法很有用,因为它默认情况下使用本代码参数执行其身份验证。
使用 HTTPQueryString 身份验证注册
您可以通过将 HttpQueryString 指定为身份验证选项来传递“查询字符串”参数。 与 HTTPHeader 选项一样,它提供了将一组键/值对传递到 Web API 的选项。 您还可以传递其他参数,甚至以这种方式通过 Azure Functions 手动传递预期的“code”参数。