Azure SignalR 服务数据平面 REST API 参考

项目
10/15/2024

除了经典客户端/服务器模式外，Azure SignalR 服务还提供了一组 REST API 来帮助将实时功能集成到无服务器体系结构中。

注意

Azure SignalR 服务支持仅使用 REST API 管理通过 ASP.NET Core SignalR 连接的客户端。通过 ASP.NET SignalR 连接的客户端使用当前不支持的其他数据协议。

使用 Azure Functions 的典型无服务器体系结构

下图显示将 Azure SignalR 服务与 Azure Functions 结合使用的典型无服务器体系结构。

此图显示 Azure SignalR 服务的典型无服务器体系结构。

negotiate 函数返回协商响应，并将所有客户端重定向到 Azure SignalR 服务。
broadcast 函数调用 Azure SignalR 服务的 REST API。 Azure SignalR 服务将消息广播到所有已连接的客户端。

在无服务器体系结构中，客户端与 Azure SignalR 服务保持持久连接。由于没有用于处理流量的应用程序服务器，客户端处于 LISTEN 模式。在该模式下，客户端可以接收消息，但无法发送消息。 Azure SignalR 服务将断开任何发送消息的客户端，因为该操作无效。

你可以在此 GitHub 存储库中找到将 Azure SignalR 服务与 Azure Functions 结合使用的完整示例。

实现协商终结点

你应该实现用于返回重定向协商响应的 negotiate 函数，以便客户端可以连接到服务。

典型的协商响应采用以下格式：

{
  "url": "https://<service_name>.signalr.azure.cn/client/?hub=<hub_name>",
  "accessToken": "<a typical JWT token>"
}

accessToken 值是通过身份验证部分中所述的同一算法生成的。唯一的区别在于，aud 声明应与 url 相同。

你应该在 https://<hub_url>/negotiate 中托管协商 API，以便仍可以使用 SignalR 客户端连接到中心 URL。在客户端连接中详细了解如何将客户端重定向到 Azure SignalR 服务。

REST API 版本

下表显示了所有支持的 REST API 版本。其中还提供了每个 API 版本的 Swagger 文件。

API 版本	状态	端口	文档	规范
`20220601`	最晚	标准	文章	Swagger 文件
`1.0`	Stable	标准	文章	Swagger 文件
`1.0-preview`	已过时	标准	文章	Swagger 文件

下表列出了可用的 API。

API	路径
将消息广播到所有连接到目标中心的客户端	`POST /api/v1/hubs/{hub}`
将消息广播到所有属于目标用户的客户端	`POST /api/v1/hubs/{hub}/users/{id}`
将消息发送到特定连接	`POST /api/v1/hubs/{hub}/connections/{connectionId}`
检查是否存在与给定 connectionId 的连接	`GET /api/v1/hubs/{hub}/connections/{connectionId}`
关闭客户端连接	`DELETE /api/v1/hubs/{hub}/connections/{connectionId}`
将消息广播到目标组中的所有客户端	`POST /api/v1/hubs/{hub}/groups/{group}`
检查给定组中是否存在任何客户端连接	`GET /api/v1/hubs/{hub}/groups/{group}`
检查是否存在任何为给定用户连接的客户端连接	`GET /api/v1/hubs/{hub}/users/{user}`
添加与目标组的连接	`PUT /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}`
从目标组中删除连接	`DELETE /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}`
检查目标组中是否存在用户	`GET /api/v1/hubs/{hub}/groups/{group}/users/{user}`
将用户添加到目标组	`PUT /api/v1/hubs/{hub}/groups/{group}/users/{user}`
从目标组中删除用户	`DELETE /api/v1/hubs/{hub}/groups/{group}/users/{user}`
从所有组中删除用户	`DELETE /api/v1/hubs/{hub}/users/{user}/groups`

使用 REST API

通过 Azure SignalR 服务中的 AccessKey 进行身份验证

在每个 HTTP 请求中，需要具有 JSON Web 令牌 (JWT) 的授权标头才能通过 Azure SignalR 服务进行身份验证。

签名算法和签名

HS256，即 HMAC-SHA256，用作签名算法。

使用 Azure SignalR 服务实例连接字符串中的 AccessKey 值对生成的 JWT 进行签名。

申请

必须在 JWT 中包含以下声明。

声明类型	必需	说明
`aud`	`true`	必须与 HTTP 请求 URL 相同，不包括反斜杠和查询参数。例如，广播请求的受众应类似于 `https://example.signalr.azure.cn/api/v1/hubs/myhub`。
`exp`	`true`	此令牌过期的纪元时间。

通过 Microsoft Entra 令牌进行身份验证

与通过 AccessKey 进行身份验证类似，需要 JWT 才能使用 Microsoft Entra 令牌对 HTTP 请求进行身份验证。

区别在于，在此方案中，JWT 令牌由 Microsoft Entra ID 生成。有关详细信息，请参阅了解如何生成 Microsoft Entra 令牌。

凭据的使用范围应为 https://signalr.azure.cn/.default。

还可以使用基于角色的访问控制 (RBAC) 授权从客户端或服务器到 Azure SignalR 服务的请求。有关详细信息，请参阅授权使用 Microsoft Entra ID 访问 Azure SignalR 服务。

若要调用与用户相关的 REST API，每个客户端都应向 Azure SignalR 服务标识自己。否则，Azure SignalR 服务无法从用户 ID 找到目标连接。

当客户端连接到 Azure SignalR 服务时，可以通过在每个客户端的 JWT 中包含 nameid 声明来实现客户端识别。然后，Azure SignalR 服务将使用 nameid 声明的值作为每个客户端连接的用户 ID。

示例

你可以在此 GitHub 存储库中找到一个完整的控制台应用，演示如何在 Azure SignalR 服务中手动生成 REST API HTTP 请求。

还可以使用 Microsoft.Azure.SignalR.Management 通过使用 IHubContext 的类似接口将消息发布到 Azure SignalR 服务。你可以在此 GitHub 存储库中找到示例。有关详细信息，请参阅 Azure SignalR 服务管理 SDK。

限制

目前，REST API 请求具有以下限制：

标头大小上限为 16 KB。
正文大小上限为 1 MB。

如果要发送大于 1 MB 的消息，请使用具有 persistent 模式的服务管理 SDK。

通过