Azure Web PubSub 服务中的事件处理程序

项目
09/04/2023

事件处理程序可处理传入的客户端事件。通过 Azure 门户或 Azure CLI 在服务中注册和配置事件处理程序。触发客户端事件时，服务可以将事件发送到相应的事件处理程序。 Web PubSub 服务现在支持将事件处理程序用作服务器端，这可以公开一个可公开访问的终结点，供服务在触发事件时调用。换言之，它用作 Webhook。

Web PubSub 服务使用 CloudEvents HTTP 协议将客户端事件传送到上游 Webhook。

服务将为每个事件构建一个 HTTP POST 请求并发送到已注册的上游终结点，并且需要 HTTP 响应。

从服务发送到服务器的数据一律采用 CloudEvents binary 格式。

Screenshot of Web PubSub service event trigger.

上游和验证

当你配置 Webhook 终结点时，URL 可以包含 {event} 参数以定义 URL 模板。当客户端请求进入时，服务会动态计算 Webhook URL 的值。例如，当请求 /client/hubs/chat 传入时，为中心 http://host.com/api/{event} 配置事件处理程序 URL 模式 chat；当连接客户端时，则率先发送到以下 URL：http://host.com/api/connect。 {event} 参数可能适用于 PubSub WebSocket 客户端发送自定义事件的情况，其中事件处理程序可帮助将不同的事件调度到不同的上游终结点。 URL 域名中不允许使用 {event} 参数。

通过 Azure 门户或 CLI 设置事件处理程序 Webhook 时，服务遵循 CloudEvents 滥用保护措施来验证上游 Webhook。每个已注册的上游 Webhook URL 都将通过此机制进行验证。 WebHook-Request-Origin 请求头设置为服务域名 xxx.webpubsub.azure.com，它会要求含标头 WebHook-Allowed-Origin 的响应包含此域名或 *。

执行验证时，{event} 参数将解析为 validate。例如，尝试将 URL 设置为 http://host.com/api/{event} 时，服务会尝试向 http://host.com/api/validate 请求执行 OPTIONS 操作。并且仅当响应有效时才可成功设置配置。

目前，我们不支持 WebHook-Request-Rate 和 WebHook-Request-Callback。

服务和 Webhook 之间的身份验证

可以使用上述任一方法在服务和 Webhook 之间进行身份验证。

匿名模式
通过配置为查询参数的 Webhook URL 提供使用 ?code=<code> 进行的简单身份验证。
Microsoft Entra 授权。有关详细信息，请参阅在客户端事件中使用托管标识。

配置事件处理程序

通过 Azure 门户进行配置

可以将事件处理程序添加到新中心，也可以编辑现有的中心。

若要在新中心内配置事件处理程序，请执行以下操作：

在 Azure 门户中转到 Azure Web PubSub 服务页。
在菜单中选择“设置”。
选择“添加”以创建中心并配置服务器端 Webhook URL。注意：若要将事件处理程序添加到现有中心，请选择该中心，然后选择“编辑”。
输入中心名称。
在“配置事件处理程序”下选择“添加”。
在事件处理程序页中配置以下字段：
1. 在“URL 模板”字段中输入服务器 Webhook URL。
2. 选择要订阅的“系统事件”。
3. 选择要订阅的“用户事件”。
4. 选择“身份验证”方法以便对上游请求进行身份验证。
5. 选择“确认”。
在“配置中心设置”页面顶部选择“保存”。

通过 Azure CLI 进行配置

使用 Azure CLI 的 az webpubsub hub 组命令配置事件处理程序设置。

命令	说明
`create`	创建 WebPubSub 服务的中心设置。
`delete`	删除 WebPubSub 服务的中心设置。
`list`	列出 WebPubSub 服务的所有中心设置。
`show`	显示 WebPubSub 服务的中心设置。
`update`	更新 WebPubSub 服务的中心设置。

下面是为 MyWebPubSub 资源的中心 MyHub 创建两个 Webhook URL 的示例：

az webpubsub hub create -n "MyWebPubSub" -g "MyResourceGroup" --hub-name "MyHub" --event-handler url-template="http://host.com" user-event-pattern="*" --event-handler url-template="http://host2.com" system-event="connected" system-event="disconnected" auth-type="ManagedIdentity" auth-resource="uri://myUri"