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

项目
09/09/2024

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

Web PubSub 服务使用 CloudEvents HTTP 协议和 Azure Web PubSub 事件处理程序的 CloudEvents 扩展将客户端事件传送到已配置的上游 Webhook。

Web PubSub 服务事件触发器的屏幕截图。

事件处理程序设置

客户端始终连接到中心，你可以为中心配置多个事件处理程序设置。事件处理程序设置的顺序很重要，前面的优先级更高。当客户端进行连接并触发事件时，Web PubSub 会按照优先级顺序检查已配置的事件处理程序，以第一个匹配的事件处理程序为准。配置事件处理程序时，应设置以下属性。

属性名称	说明
URL 模板	定义可供 Web PubSub 用来评估上游 Webhook URL 的模板。
用户事件	定义当前事件处理程序设置关注的用户事件。
系统事件	定义当前事件处理程序设置关注的系统事件。
身份验证	定义在 Web PubSub 服务和上游服务器之间使用的身份验证方法。

事件

事件包括用户事件和系统事件。系统事件是在客户端生命周期内触发的预定义事件，而用户事件是在客户端发送数据时触发的事件，用户事件名称可以使用客户端协议自定义，此处有详细说明。

事件类型	支持的值
系统事件	`connect`、`connected` 和 `disconnected`
用户事件	`message` 或遵循客户端协议的自定义事件名称

URL 模板

URL 模板支持几个可以在运行时评估的参数。使用此功能，可以轻松地通过单项设置将不同的中心或事件路由到不同的上游服务器。还支持 KeyVault 引用语法，让数据可以安全地存储在 Azure Key Vault 中。

注意 URL 域名不应包含参数语法，例如，http://{hub}.com 不是有效的 URL 模板。

支持的参数	语法	说明	示例
中心参数	`{hub}`	该值是客户端连接到的中心。	当客户端连接到 `client/hubs/chat` 时，URL 模板 `http://host.com/api/{hub}` 的计算结果为 `http://host.com/api/chat`，因为对于此客户端，中心为 `chat`。
事件参数	`{event}`	触发的事件的值。 `event` 值列于此处。滥用保护请求的事件值为 `validate`，如此处所述。	如果为事件 `connect` 配置了 URL 模板 `http://host.com/api/{hub}/{event}`，则当客户端连接到 `client/hubs/chat` 时，Web PubSub 会在客户端进行连接时向评估的 URL `http://host.com/api/chat/connect` 发起 POST 请求，因为对于此客户端事件，中心为 `chat`，而触发此事件处理程序设置的事件为 `connect`。
KeyVault 引用参数	`{@Microsoft.KeyVault(SecretUri=<secretUri>)}`	SecretUri 应该是保管库中机密的完整数据平面 URI，可以选择包含版本，例如 `https://myvault.vault.azure.cn/secrets/mysecret/` 或 `https://myvault.vault.azure.cn/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931`。使用 KeyVault 引用时，还需配置在 Web PubSub 服务和 KeyVault 服务之间使用的身份验证，详细步骤参见此文。	`@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.cn/secrets/mysecret/)`

服务和 Webhook 之间的身份验证

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

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

上游和验证

通过 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。

配置事件处理程序

通过 Azure 门户进行配置

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

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

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

通过 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"