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

# 实时消息 SignalR 中心

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

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

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

## 连接到 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://learn.microsoft.com/en-us/rest/api/playfab/multiplayer/pub-sub/negotiate)。此 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),并且将来会强制要求它作为唯一支持的编码。
</Warning>

<Info>
  客户端在构建 `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)。
</Info>

<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\)\)\))。
</Note>

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

请参阅 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](/services/playfab/multiplayer/real-time-messages/server-methods/start-or-recover-session) 以接收可用于[订阅资源](/services/playfab/multiplayer/real-time-messages/subscribing-to-resources)的 `connection handle`。同样,一旦完成会话,请调用 [EndSession](/services/playfab/multiplayer/real-time-messages/server-methods/end-session)。

## 订阅资源

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

## API

### 客户端方法

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

### 服务器方法

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

#### 共享会话方法

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

## 另请参阅

* [订阅资源](/services/playfab/multiplayer/real-time-messages/subscribing-to-resources)
* [Lobby 和 Matchmaking API 的实时消息](/services/playfab/multiplayer/real-time-messages/overview)


## Related topics

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