> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 实时消息 SignalR 中心

> 将 PlayFab Lobby 和匹配客户端连接到实时消息 SignalR 中心,包括 HubConnection 设置、MsgPack 编码和 KeepAlive 间隔。

> [!NOTE]
>
> 此处记录的 REST 和 SignalR API 比客户端 SDK 更复杂。除非这些 SDK 不能满足你的需求,否则请考虑使用 [Lobby C++ SDK](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/pflobby_members.md) 或 [Matchmaking C++ SDK](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/pfmatchmaking_members.md)。

[Lobby 和匹配服务](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/lobby/lobby-and-matchmaking.md)的实时消息功能通过 [SignalR 服务](https://learn.microsoft.com/en-us/aspnet/core/signalr)工作,该服务公开了一个 [SignalR 中心](https://learn.microsoft.com/en-us/aspnet/core/signalr/introduction#hubs)。游戏客户端可以使用此 SignalR 中心接收有关[它们所订阅资源](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/real-time-messages/subscribing-to-resources.md)的消息。

## 连接到 SignalR 中心

接收实时消息的第一步是创建一个 [SignalR 客户端](https://learn.microsoft.com/en-us/aspnet/core/signalr/client-features)。客户端可以通过使用以下 API [实例化 HubConnection](https://learn.microsoft.com/en-us/aspnet/core/signalr/dotnet-client#connect-to-a-hub) 创建到 SignalR 中心的连接:[SignalR Negotiate REST API](https://docs.xbox.com/zh-CN/services/playfab/api-references/rest/multiplayer/pub-sub/negotiate.md)。此 API 实现了 [SignalR 文档](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md#post-endpoint-basenegotiate-request)中描述的 Negotiate API。

> [!WARNING]
>
> 连接到 SignalR 中心时,强烈建议使用 [MessagePack (MsgPack) 编码](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/HubProtocol.md#messagepack-msgpack-encoding),并且将来会强制要求它作为唯一支持的编码。

> [!NOTE]
>
> 客户端在构建 `HubConnection` 时**必须**将 `KeepAliveInterval` 设置为 **5 秒**。后端服务将超时并关闭在 **10 秒**内未收到保活 ping 的连接。默认的 SignalR `KeepAliveInterval`(15 秒)太慢,会导致断开连接。 `csharp var connection = new HubConnectionBuilder() .WithUrl(hubUrl, options => { /* auth headers */ }) .WithKeepAliveInterval(TimeSpan.FromSeconds(5)) .Build(); ` 有关 SignalR 客户端配置的详细信息,请参阅 [SignalR 配置文档](https://learn.microsoft.com/en-us/aspnet/core/signalr/configuration#configure-client-options)。

> [!NOTE]
>
> 1. SignalR 客户端实现要求 URL 省略此路径的 `/negotiate` 部分(例如,应针对以 `...playfabapi.com/pubsub` 结尾的 URL 创建 HubConnection)。 1. 调用此 API 所需的身份验证头可以通过 `HttpConnectionOptions` 传递给 SignalR 客户端,[请参见此方法](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.signalr.client.hubconnectionbuilderhttpextensions.withurl#microsoft-aspnetcore-signalr-client-hubconnectionbuilderhttpextensions-withurl\(microsoft-aspnetcore-signalr-client-ihubconnectionbuilder-system-string-system-action\(\(microsoft-aspnetcore-http-connections-client-httpconnectionoptions\)\)\))。

## 实现接收消息的客户端方法

请参阅 SignalR 客户端有关[实现客户端方法](https://learn.microsoft.com/en-us/aspnet/core/signalr/dotnet-client#call-client-methods-from-hub)的文档,这些方法将被调用以接收消息。客户端应实现下面[客户端方法](#client-methods)中列出的所有方法。

## 通过调用服务器方法来启动和结束会话

请参阅 SignalR 客户端有关[调用服务器方法](https://learn.microsoft.com/en-us/aspnet/core/signalr/dotnet-client#call-hub-methods-from-client)的文档以管理会话。例如,连接到中心后,你必须调用 [StartOrRecoverSession](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/real-time-messages/server-methods/start-or-recover-session.md) 以接收可用于[订阅资源](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/real-time-messages/subscribing-to-resources.md)的 `connection handle`。同样,一旦完成会话,请调用 [EndSession](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/real-time-messages/server-methods/end-session.md)。

## 订阅资源

使用 [StartOrRecoverSession](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/real-time-messages/server-methods/start-or-recover-session.md) 启动会话后,你可以使用返回的 `connection handle` 开始[订阅资源](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/real-time-messages/subscribing-to-resources.md)并接收消息。

## API

### 客户端方法

| 名称 | 说明 |
| - | - |
| [ReceiveMessage](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/real-time-messages/client-methods/receive-message.md) | 接收消息。 |
| [ReceiveSubscriptionChangeMessage](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/real-time-messages/client-methods/receive-subscription-change-message.md) | 接收 SubscriptionChangeMessage 以跟踪当前订阅。 |

### 服务器方法

| 名称 | 说明 |
| - | - |
| [StartOrRecoverSession](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/real-time-messages/server-methods/start-or-recover-session.md) | 启动或恢复会话。 |
| [EndSession](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/real-time-messages/server-methods/end-session.md) | 结束会话。 |

#### 共享会话方法

| 名称 | 说明 |
| - | - |
| [AddEntityToSession](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/real-time-messages/server-methods/add-entity-to-session.md) | 适用于多个实体登录到同一设备的场景。向会话添加额外的实体,以在共享会话上接收多个本地实体的消息。 |
| [RemoveEntityFromSession](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/real-time-messages/server-methods/remove-entity-from-session.md) | 从会话中移除实体。 |

## 另请参阅

* [订阅资源](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/real-time-messages/subscribing-to-resources.md)
* [Lobby 和匹配 API 的实时消息](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/real-time-messages/overview.md)


## Related topics

- [订阅实时消息资源](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/real-time-messages/subscribing-to-resources.md)
- [Message 实时消息类型](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/real-time-messages/types/message.md)
- [Lobby 和 Matchmaking API 的实时消息](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/real-time-messages/overview.md)
- [EndSession SignalR 服务器方法](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/real-time-messages/server-methods/end-session.md)
- [StartOrRecoverSession SignalR 服务器方法](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/real-time-messages/server-methods/start-or-recover-session.md)