> ## 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 大廳和配對用戶端連線至即時訊息 SignalR 中樞，包括 HubConnection 設定、MsgPack 編碼和 KeepAlive 間隔。

<Note>
  這裡記載的 REST 和 SignalR API 比用戶端 SDK 更複雜。除非這些 SDK 無法滿足您的需求，否則請考慮改用[大廳 C++ SDK](/zh-TW/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/pflobby_members) 或[配對 C++ SDK](/zh-TW/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/pfmatchmaking_members)。
</Note>

[大廳和配對服務](/zh-TW/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 中樞，接收有關[其所訂閱之資源](/zh-TW/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](/zh-TW/services/playfab/multiplayer/real-time-messages/server-methods/start-or-recover-session) 以接收 `connection handle`，您可以用它來[訂閱資源](/zh-TW/services/playfab/multiplayer/real-time-messages/subscribing-to-resources)。同樣地，當您完成工作階段時，請呼叫 [EndSession](/zh-TW/services/playfab/multiplayer/real-time-messages/server-methods/end-session)。

## 訂閱資源

使用 [StartOrRecoverSession](/zh-TW/services/playfab/multiplayer/real-time-messages/server-methods/start-or-recover-session) 啟動工作階段後，您可以使用傳回的 `connection handle` 開始[訂閱資源](/zh-TW/services/playfab/multiplayer/real-time-messages/subscribing-to-resources)並接收訊息。

## API

<a id="client-methods" />

### 用戶端方法

| 名稱 | 描述 |
| - | - |
| [ReceiveMessage](/zh-TW/services/playfab/multiplayer/real-time-messages/client-methods/receive-message) | 接收訊息。 |
| [ReceiveSubscriptionChangeMessage](/zh-TW/services/playfab/multiplayer/real-time-messages/client-methods/receive-subscription-change-message) | 接收 SubscriptionChangeMessage 以追蹤目前的訂閱。 |

### 伺服器方法

| 名稱 | 描述 |
| - | - |
| [StartOrRecoverSession](/zh-TW/services/playfab/multiplayer/real-time-messages/server-methods/start-or-recover-session) | 啟動或復原工作階段。 |
| [EndSession](/zh-TW/services/playfab/multiplayer/real-time-messages/server-methods/end-session) | 結束工作階段。 |

#### 共用工作階段方法

| 名稱 | 描述 |
| - | - |
| [AddEntityToSession](/zh-TW/services/playfab/multiplayer/real-time-messages/server-methods/add-entity-to-session) | 適用於多個實體登入同一部裝置的案例。將額外實體新增至工作階段，以便在共用工作階段上接收多個本機實體的訊息。 |
| [RemoveEntityFromSession](/zh-TW/services/playfab/multiplayer/real-time-messages/server-methods/remove-entity-from-session) | 從工作階段中移除實體。 |

## 另請參閱

* [訂閱資源](/zh-TW/services/playfab/multiplayer/real-time-messages/subscribing-to-resources)
* [大廳和配對 API 的即時訊息](/zh-TW/services/playfab/multiplayer/real-time-messages/overview)


## Related topics

- [Message 即時訊息類型](/zh-TW/services/playfab/multiplayer/real-time-messages/types/message.md)
- [訂閱資源以接收即時訊息](/zh-TW/services/playfab/multiplayer/real-time-messages/subscribing-to-resources.md)
- [大廳和配對 API 的即時訊息](/zh-TW/services/playfab/multiplayer/real-time-messages/overview.md)
- [SubscriptionChangeMessage 即時訊息類型](/zh-TW/services/playfab/multiplayer/real-time-messages/types/subscription-change-message.md)
- [EndSessionRequest 即時訊息類型](/zh-TW/services/playfab/multiplayer/real-time-messages/types/end-session-request.md)