你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

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

注意

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

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

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

• 该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>.service.signalr.net/client/?hub=<hub_name>",
  "accessToken": "<a typical JWT token>"
}

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

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

REST API 版本

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

API 版本	状态	端口	文档	规范
20220601	最晚	标准	文章	Swagger 文件
1.0	Stable	标准	文章	Swagger 文件
1.0-preview	已过时	Standard	文章	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，用作签名算法。

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

申请

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

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

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

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

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

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

与用户相关的 REST API

若要调用与用户相关的 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。