上游终结点

项目
06/12/2023

上游终结点功能允许 Azure SignalR 服务以无服务器模式将消息和连接事件发送到一组终结点。可以使用上游终结点在无服务器模式下从客户端调用某个中心方法，以在客户端建立连接或断开连接时通知终结点。

注意

只能在无服务器模式下配置上游终结点。

上游终结点设置

上游终结点的设置包含一系列顺序敏感项：

一个 URL 模板，它指定将消息发送到的位置。
一组规则。
身份验证配置。

触发事件时，将按顺序逐个检查项的规则。消息将发送到第一个匹配项的上游终结点 URL。

URL 模板设置

可以将上游终结点 URL 参数化以支持各种模式。有三个预定义的参数：

预定义的参数	说明
{hub}	中心是 Azure SignalR 服务的一个概念。中心是一个隔离单元。用户和消息传递的作用域被限定为某个中心。
{category}	类别可以是下列值之一：连接：连接生存期事件。它在客户端建立连接或断开连接时引发。它包括“已连接”事件和“已断开连接”事件。消息：当客户端调用某个中心方法时引发。它包含除“连接”类别中事件之外的所有其他事件。
{event}	对于“消息”类别，事件是客户端发送的调用消息中的目标。对于“连接”类别，只使用“已连接”和“已断开连接” 。

这些预定义参数可用于 URL 模式。在评估上游终结点 URL 时，参数将替换为某个指定的值。例如：

http://host.com/{hub}/api/{category}/{event}

当“聊天”中心内建立了某个客户端连接时，会向以下 URL 发送消息：

http://host.com/chat/api/connections/connected

当“聊天”中心内的客户端调用中心方法 broadcast 时，会向以下 URL 发送消息：

http://host.com/chat/api/messages/broadcast

URL 模板设置中的 Key Vault 机密引用

上游终结点 URL 未加密。可以使用 Key Vault 保护敏感的上游终结点，并使用托管标识访问它们。

若要在 SignalR 服务实例中启用托管标识并授予其 Key Vault 访问权限，请执行以下操作：

添加系统分配的标识或用户分配的标识。请参阅如何在 Azure 门户中添加托管标识。
在 Key Vault 的访问策略中授予对托管标识的机密读取权限。请参阅使用 Azure 门户分配 Key Vault 访问策略
在上游终结点 URL 模式中将敏感文本替换为以下语法：
```
{@Microsoft.KeyVault(SecretUri=<secret-identity>)}
```
<secret-identity> 是 Key Vault 中机密的完整数据平面 URI，可以选择包括版本，例如 https://myvault.vault.azure.cn/secrets/mysecret/ 或 https://myvault.vault.azure.cn/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931

例如，完整的引用将如下所示：
```
{@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.cn/secrets/mysecret/)}
```
Azure 函数的上游终结点 URL 如下所示：
```
https://contoso.chinacloudsites.cn/runtime/webhooks/signalr?code={@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.cn/secrets/mysecret/)}
```

注意

每隔 30 分钟，或者每当上游终结点设置或托管标识发生更改时，该服务就会重新读取机密内容一次。可以通过更改上游终结点设置立即触发更新。

规则设置

可以分别设置“中心规则”、“类别规则”和“事件规则”。匹配规则支持三种格式：

使用星号 (*) 来匹配任何事件。
使用逗号 (,) 来联接多个事件。例如，connected, disconnected 匹配“已连接”和“已断开连接”事件。
使用完整的事件名称来匹配事件。例如，connected 匹配“已连接”事件。

注意

如果将 Azure Functions 和 SignalR 触发器配合使用，则 SignalR 触发器将按以下格式公开单个终结点：<Function_App_URL>/runtime/webhooks/signalr?code=<API_KEY>。只需为此 URL 配置“URL 模板设置”，并将“规则设置”保留为默认值。有关如何查找 <Function_App_URL> 和 <API_KEY> 的详细信息，请参阅 SignalR 服务集成。

身份验证设置

你可以分别为每个上游终结点设置配置身份验证。配置身份验证时，会在上游消息的 Authentication 标头中设置令牌。目前，Azure SignalR 服务支持以下身份验证类型：

None
ManagedIdentity

选择 ManagedIdentity 时，必须首先在 Azure SignalR 服务中启用托管标识，并且可以根据需要指定资源。有关详细信息，请参阅 Azure SignalR 服务的托管标识。

通过 Azure 门户配置上游终结点设置

注意

当前不支持与应用服务环境集成。

转到“Azure SignalR 服务”。
选择“设置”。
将“服务模式”切换为“无服务器”。
在“上游 URL 模式”下添加 URL。
选择“中心规则”以打开“上游设置”。
通过在相应字段中输入规则值来更改“中心规则”、“事件规则”和“类别规则”。
在“上游身份验证”下选择
“使用托管标识”。（确保已启用托管标识）
在“颁发的令牌中的受众”下选择任意选项。有关详细信息，请参阅 Azure SignalR 服务的托管标识。

通过资源管理器模板配置上游终结点设置

若要使用 Azure 资源管理器模板配置上游终结点设置，请在 properties 属性中设置 upstream 属性。以下代码片段显示了如何设置用于创建和更新上游终结点设置的 upstream 属性。

{
  "properties": {
    "upstream": {
      "templates": [
        {
          "UrlTemplate": "http://host.com/{hub}/api/{category}/{event}",
          "EventPattern": "*",
          "HubPattern": "*",
          "CategoryPattern": "*",
          "Auth": {
            "Type": "ManagedIdentity",
            "ManagedIdentity": {
              "Resource": "<resource>"
            }
          }
        }
      ]
    }
  }
}

无服务器协议

Azure SignalR 服务将消息发送到遵循以下协议的终结点。可以将 SignalR 服务触发器绑定用于处理这些协议的 Function App。

方法

POST

请求头

名称	说明
X-ASRS-Connection-Id	客户端连接的连接 ID。
X-ASRS-Hub	客户端连接所属的中心。
X-ASRS-Category	消息所属的类别。
X-ASRS-Event	消息所属的事件。
X-ASRS-Signature	一个基于哈希的消息身份验证代码 (HMAC)，用于验证。有关详细信息，请参阅签名。
X-ASRS-User-Claims	客户端连接的一组声明。
X-ASRS-User-Id	发送消息的客户端的用户标识。
X-ASRS-Client-Query	客户端连接到服务时的请求的查询。
身份验证	使用 `ManagedIdentity` 时的一个可选令牌。

请求正文

连续

Content-Type：application/json

已断开连接