> ## 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.

# Matchmaking 快速入门

> 在 Unity 中演练完整的 PlayFab Matchmaking 流程:使用 Multiplayer SDK 创建工单、轮询状态并检索对局结果。

# Matchmaking REST API 快速入门

<Note>
  我们强烈建议你考虑使用 Multiplayer SDK,因为它包含实时消息支持,可减少轮询需求。这将改善匹配体验并降低延迟。[快速入门 - Client SDK](/services/playfab/multiplayer/matchmaking/quickstart-client-sdk)
</Note>

本快速入门指南将引导你完成集成匹配功能的整个流程。本快速入门中的所有代码示例均适用于 Unity——不过,概念和流程(总体上)同样适用于其他平台。

根据你的游戏设计,请考虑[单个用户](#single-user-ticket-matchmaking)和[多个用户](#multiple-user-ticket-matchmaking)匹配部分。

本教程演示如何向特定队列提交工单以查找对局。一个队列可能对应一种游戏模式或多种游戏模式(例如,同一队列中的“夺旗”模式和“山丘之王”模式)。

匹配服务负责在队列中的工单之间寻找对局。找到对局后,你的游戏必须处理将玩家连接在一起以进行游戏。

## 在 Game Manager 中配置匹配队列

本快速入门假定你已在 Game Manager 中配置好了队列。有关如何设置的详细信息,请参阅[配置匹配队列](/services/playfab/multiplayer/matchmaking/config-queues)。

## 单用户工单匹配

如果你的游戏有 1v1 游戏模式,或支持单个用户独自进入匹配,请考虑单用户匹配。单用户匹配遵循下面所示的模式。

<img src="https://mintcdn.com/microsoft-4404708b/dqv53299jA1M-fNi/images/playfab/multiplayer/matchmaking/quickstart/matchmaking-single-user-flow.png?fit=max&auto=format&n=dqv53299jA1M-fNi&q=85&s=7a34b642c26c3ab073ca258bae379604" alt="Matchmaking Flow" width="708" height="460" data-path="images/playfab/multiplayer/matchmaking/quickstart/matchmaking-single-user-flow.png" />

### 创建匹配工单

用户使用 [CreateMatchmakingTicket](xref:titleid.playfabapi.com.multiplayer.matchmaking.creatematchmakingticket) 创建匹配工单。工单创建成功时,服务返回一个 `TicketId`。

工单创建要求你指定 `Creator`(用户的身份和属性)、`GiveUpAfterSeconds`(服务放弃匹配工单之前的时间(以秒为单位))以及要在其中查找对局的 `QueueName`。

`Creator` 字段必须包含与 `QueueName` 匹配的队列配置所要求的用户属性。`GiveUpAfterSeconds` 时间的合适值为 120 秒,以防止用户自行放弃。

```csharp theme={null}
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](xref:titleid.playfabapi.com.multiplayer.matchmaking.getmatchmakingticket)。你每分钟最多可轮询 10 次。例如,每 6 秒轮询一次工单状态。轮询可能会增加检索工单状态时的延迟。因此,我们强烈建议你考虑使用[快速入门 - Client SDK](/services/playfab/multiplayer/matchmaking/quickstart-client-sdk) 中所述的 Multiplayer SDK 方法。它通过使用实时消息功能,避免了轮询的需要。

当工单的状态变为 `Matched` 时,你的客户端可以停止轮询工单。从那时起,工单将包含 `MatchId`。

```csharp theme={null}
PlayFabMultiplayerAPI.GetMatchmakingTicket(
    new GetMatchmakingTicketRequest
    {
        TicketId = "<ticket ID goes here>",
        QueueName = "myqueue",
    },
    this.OnGetMatchmakingTicket,
    this.OnMatchmakingError);
```

### 获取对局

从你的客户端,使用 [GetMatchmakingTicket](xref:titleid.playfabapi.com.multiplayer.matchmaking.getmatchmakingticket) 响应中提供的 `MatchId` 调用 [GetMatch](xref:titleid.playfabapi.com.multiplayer.matchmaking.getmatch)。此对局包含被匹配到一起的用户列表。

```csharp theme={null}
PlayFabMultiplayerAPI.GetMatch(
    new GetMatchRequest
    {
        MatchId = "<match ID goes here>",
        QueueName = "myqueue",
    },
    this.OnGetMatch,
    this.OnMatchmakingError);
```

### 取消匹配工单

如果你的客户端出于某种原因希望在达到 `GiveUpAfterSeconds` 之前取消匹配过程,请使用 `TicketId` 调用 [CancelMatchmakingTicket](xref:titleid.playfabapi.com.multiplayer.matchmaking.cancelmatchmakingticket)。如果尚未找到对局,则工单将从匹配过程中移除,其状态将变为 `Canceled`。

```csharp theme={null}
PlayFabMultiplayerAPI.CancelMatchmakingTicket(
    new CancelMatchmakingTicketRequest
    {
        QueueName = "myqueue",
        TicketId = "<ticket ID goes here>",
    },
    this.OnTicketCanceled,
    this.OnMatchmakingError);
```

## 多用户工单匹配

如果你的游戏允许一组玩家一起进入匹配队列,则进入匹配还需要做一些额外的事情。我们建议你的游戏指定一个组长(创建者),以避免不必要的调用。组长创建工单,但组的所有成员必须同意加入。

### 创建匹配工单(多用户)

该组必须在你的游戏中选出一个工单创建者。创建者使用 [CreateMatchmakingTicket](xref:titleid.playfabapi.com.multiplayer.matchmaking.creatematchmakingticket) 创建匹配工单,成功时返回一个 `TicketId`。工单创建要求你指定 `Creator`(用户的身份和属性)、`GiveUpAfterSeconds`(服务放弃匹配工单之前的时间(以秒为单位))、`MembersToMatchWith`(组中其他成员的身份)以及要在其中查找对局的 `QueueName`。

`Creator` 字段必须包含与 `QueueName` 匹配的队列配置所要求的用户属性。`GiveUpAfterSeconds` 时间的合适值为 120 秒,以防止用户自行放弃。

### 组成员加入匹配工单

匹配工单创建后,组的其他成员必须加入它才能继续匹配过程。此时,工单处于 `WaitingForPlayers` 状态。在所有 `MembersToMatchWith` 加入工单之前,它不会开始与其他工单匹配。

要让成员加入,`Creator` 必须通过你的游戏将 `TicketId` 分享给其他成员。然后每个成员调用 [JoinMatchmakingTicket](xref:titleid.playfabapi.com.multiplayer.matchmaking.joinmatchmakingticket),提供自己所需的属性。所有成员加入工单后,工单状态将变为 `WaitingForMatch`。

```csharp theme={null}
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);
```

其余流程与[单用户工单匹配](#single-user-ticket-matchmaking)相同。

### 将玩家连接在一起

玩家匹配后,你需要让他们相互加入——通过服务器,或通过点对点连接。

如果使用专用服务器,可以依靠 Match ID 来唯一识别他们应处于的玩家组。如果使用 PlayFab 的多人游戏服务器,`GetMatch` 会提供供玩家连接的服务器和端口。

有关更多信息,请参阅[与 PlayFab Multiplayer Servers 集成](/services/playfab/multiplayer/matchmaking/multiplayer-servers)。

截至本版本,匹配目前未正式支持点对点连接。如果需要点对点,请考虑使用 [PlayFab Party](/services/playfab/multiplayer/networking) 或[临时变通方法](/services/playfab/multiplayer/matchmaking/peer-to-peer)。有关此方面的更多支持,请与我们联系。

## 结论

使用本快速入门,你现在应该在游戏中拥有一个成功的匹配流程。此外,你还应考虑以下方面:

* 你的游戏如何处理组的形成。
* 玩家等待对局时你的游戏显示什么。
* 如何处理失败和重试。


## Related topics

- [Matchmaking SDK 快速入门](/zh-CN/services/playfab/multiplayer/matchmaking/quickstart-client-sdk.md)
- [Lobby SDK 快速入门](/zh-CN/services/playfab/multiplayer/lobby/lobby-getting-started.md)
- [快速入门](/zh-CN/services/playfab/economy-monetization/economy-v2/quickstart.md)
- [Multiplayer Unity 插件快速入门](/zh-CN/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/multiplayer-unity-plugin-quickstart.md)
- [Android 快速入门](/zh-CN/services/playfab/sdks/c/quickstart-android.md)