匹配 REST API 快速入门
注意
强烈建议考虑使用多人游戏 SDK，因为它包括实时通知支持，从而减少了轮询需求。 这将改善匹配体验并减少延迟。 快速入门 - 客户端 SDK
本快速入门指南将指导您完成集成匹配功能的整个过程。 本快速入门中的所有代码示例均针对 Unity - 但概念和流程（总体上）也适用于其他平台。
本教程说明如何将票证提交到特定队列，以便查找游戏。 队列可能映射到一个游戏模式或多个游戏模式（例如：同一队列中的夺旗模式和山丘之王模式）。
匹配服务处理队列中的票证之间查找匹配。 找到匹配后，游戏必须将玩家连接在一起来玩游戏。
在 Game Manager 中配置匹配队列
本快速入门假定你已在 Game Manager 中配置了队列。 有关如何设置匹配队列的详细信息，请参阅 配置匹配队列。
单用户票证匹配
如果游戏是一对一游戏模式，或者支持单用户自行进入匹配，可考虑使用单用户匹配。 单用户匹配遵循下面所示的模式。
创建匹配票证
用户使用 CreateMatchmakingTicket 创建匹配票证。 票证创建成功后，该服务返回 TicketId。
票证创建要求您指定 Creator（用户的身份和属性）、GiveUpAfterSeconds（服务放弃匹配票证前的秒数），以及查找匹配所在的 QueueName。
Creator 字段必须包含与 QueueName 匹配的队列配置所需的用户属性。 为防止用户自行放弃，最好将 GiveUpAfterSeconds 时间的值设置为 120 秒。
PlayFabMultiplayerAPI.CreateMatchmakingTicket(
new CreateMatchmakingTicketRequest
{
// The ticket creator specifies their own player attributes.
Creator = new MatchmakingPlayer
{
Entity = new EntityKey
{
Id = "<Entity ID goes here>",
Type = "<Entity type goes here>",
},
// Here we specify the creator's attributes.
Attributes = new MatchmakingPlayerAttributes
{
DataObject = new
{
Skill = 24.4
},
},
},
// Cancel matchmaking if a match is not found after 120 seconds.
GiveUpAfterSeconds = 120,
// The name of the queue to submit the ticket into.
QueueName = "myqueue",
},
// Callbacks for handling success and error.
this.OnMatchmakingTicketCreated,
this.OnMatchmakingError);
检查匹配票证的状态
您必须按 TicketId 轮询服务，才能访问匹配中票证的 Status。 为执行此操作，让游戏调用 GetMatchmakingTicket。 每分钟最多可轮询 10 次。 例如，每 6 秒轮询一次票证状态。 检索票证状态时，轮询可能会增加延迟。 正因如此，我们强烈建议考虑使用此 快速入门 - 客户端 SDK 中所述的多人游戏 SDK 方法。 这样可以避免使用实时通知功能轮询。
当票证的状态变为 Matched 时，客户端可停止轮询票证。 从那时起，票证将包含 MatchId。
PlayFabMultiplayerAPI.GetMatchmakingTicket(
new GetMatchmakingTicketRequest
{
TicketId = "<ticket ID goes here>",
QueueName = "myqueue",
},
this.OnGetMatchmakingTicket,
this.OnMatchmakingError);
获得匹配
从客户端，使用来自 GetMatchmakingTicket 的响应中提供的 MatchId 调用 GetMatch。 此匹配包含匹配在一起的用户的列表。
PlayFabMultiplayerAPI.GetMatch(
new GetMatchRequest
{
MatchId = "<match ID goes here>",
QueueName = "myqueue",
},
this.OnGetMatch,
this.OnMatchmakingError);
取消匹配票证
如果出于某种原因，客户端需要在达到 GiveUpAfterSeconds 前取消匹配过程，请使用 TicketId 调用 CancelMatchmakingTicket。 如果尚未发现匹配，则会从匹配过程中取出票证，并且其状态将变为 Canceled。
PlayFabMultiplayerAPI.CancelMatchmakingTicket(
new CancelMatchmakingTicketRequest
{
QueueName = "myqueue",
TicketId = "<ticket ID goes here>",
},
this.OnTicketCanceled,
this.OnMatchmakingError);
多用户票证匹配
如果游戏允许玩家组一起进入匹配队列，则还需要执行更多操作才能进入匹配。 建议您的游戏指定一个组长（创建者），以免进行不必要的调用。 组长创建票证，但该组的所有成员都必须同意加入该票证。
创建匹配票证（多用户）
该组必须在游戏中选择一个票证创建者。 创建者使用 CreateMatchmakingTicket 创建匹配票证，成功时返回 TicketId。 票证创建要求您指定 Creator（用户的身份和属性）、GiveUpAfterSeconds（服务放弃匹配票证前的秒数）、MembersToMatchWith（其他组成员的身份）以及查找匹配所在的 QueueName。
Creator 字段必须包含与 QueueName 匹配的队列配置所需的用户属性。 为防止用户自行放弃，最好将 GiveUpAfterSeconds 时间的值设置为 120 秒。
组成员加入匹配票证
创建了匹配票证后，该组的其他成员必须加入该票证才能继续此匹配过程。 此时，该票证处于 WaitingForPlayers 状态。 在所有 MembersToMatchWith 均加入该票证前，不会开始与其他票证进行匹配。
要让成员加入，Creator 必须通过游戏与其他成员共享 TicketId。 然后每个成员都调用 JoinMatchmakingTicket，从而提供他们自己的必需属性。 所有成员均加入该票证后，票证状态变为 WaitingForMatch。
PlayFabMultiplayerAPI.JoinMatchmakingTicket(
new JoinMatchmakingTicketRequest
{
TicketId = "<ticket ID>",
QueueName = "myqueue",
Member = new MatchmakingPlayer
{
Entity = new EntityKey
{
Id = "<Entity ID goes here>",
Type = "<Entity type goes here>",
},
Attributes = new MatchmakingPlayerAttributes
{
DataObject = new
{
Skill = 19.3
},
},
}
},
this.OnJoinMatchmakingTicket,
this.OnMatchmakingError);
该过程的其余部分与单用户票证匹配过程相同
将玩家连接在一起
玩家匹配后，您需要让他们互相加入 - 通过服务器或通过对等连接。
如果使用专用服务器，可通过匹配 ID 唯一识别玩家应属于的玩家组。 如果使用 PlayFab 的多人游戏服务器，GetMatch 将提供玩家要连接到的服务器和端口。
有关详细信息，请参阅与 PlayFab 多人游戏服务器集成。
截至本版本，匹配当前未正式支持对等连接。 如果需要对等，请考虑使用 Playfab Party 或[临时解决方法。 请联系我们，以便获得有关这方面的更多支持。
总结
通过使用本快速入门，您的游戏现在已有了成功的匹配流程。 此外，您还应该考虑：
- 您的游戏如何处理组形成。
- 在用户等待匹配时您的游戏显示的内容。
- 如何处理失败和重试。