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

# 使用服务器回填工单 - REST API

> 通过 REST API 创建和管理 PlayFab Matchmaking 回填工单,将玩家添加到已在进行中的对局中,并使游戏服务器保持满员。

<Note>
  我们强烈建议你考虑使用 Multiplayer SDK,因为它包含实时消息支持,可减少轮询需求,改善匹配体验并降低延迟。[使用服务器回填工单 - Multiplayer SDK](/services/playfab/multiplayer/matchmaking/backfill-tickets-multiplayer-sdk)
</Note>

服务器上托管的游戏有时会需要搜索额外的玩家。这种情况最常发生在游戏进行过程中一名或多名玩家断开连接时。服务器回填工单允许游戏服务器搜索适合当前正在进行的游戏的额外玩家。

服务器回填工单在多个方面与常规匹配工单不同:

1. 匹配
   * 回填工单彼此之间不能匹配。
   * 回填工单在搜索期间被赋予优先级。这可减少玩家群体的碎片化。
2. 契约
   * 可使用 `ServerDetails` 字段创建回填工单。这允许服务器指示已匹配的玩家应如何连接到该服务器。
   * 可使用团队分配创建回填工单。这允许具有团队机制的游戏保持其团队信息。
3. 队列属性
   * 回填工单不会触发 [Multiplayer Server 分配](/services/playfab/multiplayer/matchmaking/multiplayer-servers)。
   * 回填工单不会反映在[队列统计信息](/services/playfab/multiplayer/matchmaking/display-statistics)中,因为其玩家已经在进行游戏,会不准确地影响等待时间。
4. 所有权
   * 回填工单由游戏服务器所有,而非用户。用户无法以任何方式查看或操作回填工单。

## 创建服务器回填工单

回填过程的开始与创建常规匹配工单类似,但使用的是 [CreateServerBackfillTicket](https://learn.microsoft.com/en-us/rest/api/playfab/multiplayer/matchmaking/create-server-backfill-ticket) 调用,而不是 [CreateServerMatchmakingTicket](xref:titleid.playfabapi.com.multiplayer.matchmaking.createservermatchmakingticket) 调用。游戏服务器必须为其当前托管的游戏提供所有成员信息。最有效的方式是存储先前对局结果中返回的属性。可通过使用 `ReturnMemberAttributes` 标志调用 [GetMatch](xref:titleid.playfabapi.com.multiplayer.matchmaking.getmatch) 来检索这些属性。或者,游戏服务器也可以向用户查询属性信息。

除了成员之外,游戏服务器还可以指定另外两条信息。

### ServerDetails

此结构与 [GetMatch](xref:titleid.playfabapi.com.multiplayer.matchmaking.getmatch) 调用返回的结构相同,允许服务器指定连接到它所需的任何信息。当回填工单被匹配时,其 [ServerDetails](xref:titleid.playfabapi.com.multiplayer.matchmaking.getmatch#serverdetails) 结构会返回给对生成对局调用 [GetMatch](xref:titleid.playfabapi.com.multiplayer.matchmaking.getmatch) 的任何玩家。此结构中的所有字段都是可选的。游戏可能只需要其中的一部分即可为客户端连接到游戏服务器提供足够的信息。

<Note>
  `IPV4Address` 字段不会被验证,可用于向客户端提供任意的连接字符串信息。
</Note>

```json theme={null}
{
  "ServerDetails": {
    "IPV4Address": "123.234.123.234",
    "Ports": [
      {
        "Port": {
          "Name": "portname",
          "Num": 12345,
          "Protocol": "UDP"
        }
      }
    ],
    "Region": "EastUS"
  }
}
```

### 团队分配

如果回填工单被提交到具有团队的队列中,每个成员还可以指定一个 TeamId,以指示他们当前所在的团队。当返回对局时,此成员身份将得到保留。如果未为用户指定 TeamId,则可以将其放入任何团队。

```json theme={null}
{
  "Members": [
    {
      "TeamId": "red",
      "Entity": {
        "Id": "6570DE3537DC9DF6",
        "Type": "title_player_account",
        "TypeString": "title_player_account"
      },
      "Attributes": {
        "DataObject": {
          "Skill": 25
        }
      }
    }
  ]
}
```

## 与回填工单交互

回填工单创建后,便开始搜索满足规则条件的常规匹配工单。回填工单的流程与常规匹配工单的操作方式相同,只是使用相应的 API。游戏服务器可以通过调用 [GetServerBackfillTicket](https://learn.microsoft.com/en-us/rest/api/playfab/multiplayer/matchmaking/create-server-backfill-ticket) 检查其工单的状态。也可以通过调用 [CancelServerBackfillTicket](https://learn.microsoft.com/en-us/rest/api/playfab/multiplayer/matchmaking/cancel-server-backfill-ticket?view=playfab-rest) 取消工单。

<Note>
  客户端不允许取消其所在的回填工单。假设某个客户端处于 4v4 对局中,而对方团队有一名玩家掉线。若允许客户端持续取消其所在的所有回填工单,该客户端便可以维持其优势。为防止这种情况,只有游戏服务器可以取消回填工单。
</Note>

## 成员资格限制以及从丢失的回填工单中恢复

与常规匹配工单类似,任何时候用户在每个队列中只能位于一个回填工单中。此限制与客户端控制的常规工单分别跟踪。

如果游戏服务器创建了回填工单然后崩溃,由于成员资格限制,丢失的回填工单中的任何用户都将无法被提交到另一个回填工单中。游戏服务器会通过收到错误 `MatchmakingTicketMembershipLimitExceeded` 以及在 `errorDetails` 正文中列出哪些用户存在未处理的回填工单来发现这一情况。

```json theme={null}
{
    "code": 400,
    "status": "BadRequest",
    "error": "MatchmakingTicketMembershipLimitExceeded",
    "errorCode": 2055,
    "errorMessage": "User is a member of too many backfill tickets.",
    "errorDetails": {
        "UsersExceedingMembershipLimit": [
            "title_player_account!562D72A5B184F612"
        ]
    }
}
```

游戏服务器可通过调用 [CancelAllServerBackfillTicketsForPlayer](https://learn.microsoft.com/en-us/rest/api/playfab/multiplayer/matchmaking/cancel-all-server-backfill-tickets-for-player) 从这种情况中恢复用户,该 API 会移除用户所在的所有回填工单。此外还提供了 [ListServerBackfillTicketsForPlayer](https://learn.microsoft.com/en-us/rest/api/playfab/multiplayer/matchmaking/list-server-backfill-tickets-for-player) 作为一种方法,用于发现玩家可能所在的回填工单。

## 与区域选择规则的交互

区域选择规则通常要求工单为其属性指定一个延迟测量的数组。然而,回填工单代表的是特定数据中心中已在进行的游戏。创建请求时必须在 [ServerDetails](xref:titleid.playfabapi.com.multiplayer.matchmaking.getmatch#serverdetails) 结构中指定一个区域,而不是延迟测量数组。为了使工单与回填工单匹配,它们必须对回填工单所指定的区域具有可接受的 ping 时间。

## 与团队工单大小相似度规则的交互

团队工单大小相似度规则强制大型玩家群体与其他大型玩家群体匹配。然而,回填工单不包含哪些玩家作为一组加入游戏的信息。因此,在匹配回填工单时,工单大小相似度规则将被忽略。


## Related topics

- [使用服务器回填工单 - Multiplayer SDK](/zh-CN/services/playfab/multiplayer/matchmaking/backfill-tickets-multiplayer-sdk.md)
- [CreateServerBackfillTicket](/zh-CN/services/playfab/multiplayer/lobby/unity-multiplayer-api-reference/PlayFab.Multiplayer/PlayFabMultiplayer.PlayFabMultiplayerServer/CreateServerBackfillTicket.md)
- [同时使用大厅和匹配](/zh-CN/services/playfab/multiplayer/lobby/lobby-and-matchmaking.md)
- [PlayFab Multiplayer C++ SDK 发行说明](/zh-CN/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/lobby-and-matchmaking-release-notes.md)
- [使用 PlayFab 的多人游戏](/zh-CN/services/playfab/multiplayer/mpintro.md)