跳轉到主要內容

配對 REST API 快速入門

強烈建議您考慮使用 Multiplayer SDK,因為它包含即時訊息支援,可減少輪詢的需求。這將改善配對體驗並減少延遲。快速入門 - 用戶端 SDK
本快速入門指南會逐步引導您完成整合配對功能的整個程序。本快速入門中的所有程式碼範例都適用於 Unity,不過,其概念和流程 (一般而言) 也適用於其他平台。 視您的遊戲設計而定,請參考單一使用者和多使用者配對章節。 本教學課程說明如何將票證提交至特定佇列以尋找遊戲。佇列可能對應到一種或多種遊戲模式 (例如:同一個佇列中的搶旗模式和山丘之王模式)。 配對服務負責在佇列中的票證之間尋找比賽。找到比賽時,您的遊戲必須負責將玩家連線在一起進行遊戲。

在 Game Manager 中設定配對佇列

本快速入門假設您已在 Game Manager 中設定佇列。如需如何設定佇列的詳細資料,請參閱設定配對佇列.

單一使用者票證配對

如果您的遊戲有 1 對 1 遊戲模式,或支援單一使用者自行進入配對,請考慮使用單一使用者配對。單一使用者配對遵循下圖所示的模式。 配對流程

建立配對票證

使用者使用 CreateMatchmakingTicket 建立配對票證。成功建立票證時,服務會傳回 TicketId。 建立票證時,您必須指定 Creator (使用者的身分識別和屬性)、GiveUpAfterSeconds (服務放棄配對票證前的時間,以秒為單位),以及要在其中尋找比賽的 QueueName。 Creator 欄位必須包含與 QueueName 相符之佇列設定所需的使用者屬性。GiveUpAfterSeconds 時間的理想值為 120 秒,以避免使用者自行放棄。

檢查配對票證的狀態

您必須依 TicketId 輪詢服務,才能存取配對中票證的 Status。為此,請讓您的遊戲呼叫 GetMatchmakingTicket。您每分鐘最多可以輪詢 10 次。例如,每 6 秒輪詢一次票證狀態。輪詢可能會增加擷取票證狀態時的延遲。基於這個原因,強烈建議您考慮使用此處所述的 Multiplayer SDK 方法:快速入門 - 用戶端 SDK。這會使用即時訊息功能,從而避免輪詢的需求。 當票證狀態變更為 Matched 時,您的用戶端就可以停止輪詢票證。從那時起,票證會包含 MatchId。

取得比賽

從您的用戶端,使用 GetMatchmakingTicket 回應中提供的 MatchId 呼叫 GetMatch。此比賽包含已配對在一起的使用者清單。

取消配對票證

如果您的用戶端基於某些原因想要在達到 GiveUpAfterSeconds 之前取消配對程序,請使用 TicketId 呼叫 CancelMatchmakingTicket。如果尚未找到比賽,票證會從配對程序中移除,其狀態會變更為 Canceled。

多使用者票證配對

如果您的遊戲允許玩家群組一起進入配對佇列,則進入配對還需要完成一些其他事項。建議您的遊戲指派一位群組領導者 (建立者),以避免進行不必要的呼叫。領導者會建立票證,但群組的所有成員都必須同意加入。

建立配對票證 (多使用者)

群組必須在您的遊戲中選出一位票證建立者。建立者使用 CreateMatchmakingTicket 建立配對票證,成功時會傳回 TicketId。建立票證時,您必須指定 Creator (使用者的身分識別和屬性)、GiveUpAfterSeconds (服務放棄配對票證前的時間,以秒為單位)、MembersToMatchWith (其他群組成員的身分識別),以及要在其中尋找比賽的 QueueName。 Creator 欄位必須包含與 QueueName 相符之佇列設定所需的使用者屬性。GiveUpAfterSeconds 時間的理想值為 120 秒,以避免使用者自行放棄。

群組成員加入比賽票證

建立比賽票證後,群組的其他成員必須加入票證,配對程序才能繼續進行。此時,票證處於 WaitingForPlayers 狀態。在所有 MembersToMatchWith 都加入票證之前,它不會開始與其他票證配對。 若要讓成員加入,Creator 必須透過您的遊戲將 TicketId 分享給其他成員。接著,每位成員都會呼叫 JoinMatchmakingTicket,並提供自己的必要屬性。所有成員都加入票證後,票證狀態會變成 WaitingForMatch。
其餘程序與單一使用者票證配對相同

將玩家連線在一起

玩家配對成功後,您會想要讓他們彼此連線,可以透過伺服器,或透過對等連線。 如果您使用專用伺服器,可以依賴比賽識別碼來唯一識別玩家應所屬的群組。如果您使用 PlayFab 的多人遊戲伺服器,GetMatch 會提供伺服器和連接埠供玩家連線。 如需詳細資訊,請參閱與 PlayFab Multiplayer Servers 整合. 截至此版本,配對目前不正式支援對等連線。如果需要對等連線,請考慮使用 PlayFab Party,或使用暫時的因應措施。如需這方面的更多支援,請與我們連絡。

結論

透過本快速入門,您的遊戲現在應該已經有可正常運作的配對流程。此外,您應該考慮下列事項:
  • 您的遊戲如何處理群組組成。
  • 使用者等候比賽時,您的遊戲要顯示什麼內容。
  • 如何處理失敗和重試。
最後修改於 2026年10月8日