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

  • 项目

除了经典客户端-服务器模式外，Azure SignalR 服务还提供了一组 REST API，你可通过这些 API 轻松地将实时功能集成到无服务器体系结构中。

注意

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

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

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

Diagram of a typical serverless architecture for Azure SignalR service

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

在无服务器体系结构中，客户端仍与 SignalR 服务保持持久连接。 由于没有用于处理流量的应用程序服务器，因此客户端处于 LISTEN 模式，这意味着它们只能接收消息而不能发送消息。 SignalR 服务将断开任何发送消息的客户端，因为该操作无效。

可在此处找到将 SignalR 服务与 Azure Functions 结合使用的完整示例。

API

下表显示了所有支持的 REST API 版本。 还可以查找每个版本的 REST API 的 swagger 文件。

API 版本 状态 端口 Doc 规范
20220601 最晚 标准 Doc swagger
1.0 Stable 标准 Doc swagger
1.0-preview 已过时 标准 Doc 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) 的授权标头才能通过 SignalR 服务进行身份验证。

签名算法和签名

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

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

声明

在 JWT 令牌中需要包含以下声明。

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

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

与使用 AccessKey 进行身份验证类似，在使用 Microsoft Entra 令牌进行身份验证时，还需要 JSON Web 令牌 (JWT) 才能对 HTTP 请求进行身份验证。

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

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

实现协商终结点

如体系结构部分中所示，你应该实现用于返回重定向协商响应的 negotiate 函数，以便客户端可以连接到服务。 典型的协商响应如下所示：

{
  "url":"https://<service_name>.service.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，每个客户端都应向 SignalR 服务标识自己， 否则 SignalR 服务无法从给定的用户 ID 中找到目标连接。

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

示例

可在此处找到一个完整的控制台应用，用于演示如何在 SignalR 服务中手动生成 REST API HTTP 请求。

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

限制

目前，我们对 REST API 请求有以下限制：

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

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