使用服务器回填票证 - REST API

项目
02/21/2025

注意

强烈建议你考虑使用多人游戏 SDK，因为它包括实时通知支持，可减少轮询需求、改善匹配体验并减少延迟。使用服务器回填票证 - 多人游戏 SDK

服务器上托管的游戏有时会发现需要搜索额外的玩家。大多数情况下，当游戏正在进行时，一个或多个玩家断开连接时会发生这种情况。服务器回填票证允许游戏服务器搜索适合当前正在玩的游戏的额外玩家。

服务器回填票证在多个方面与常规匹配票证不同：

匹配
- 回填票证不能相互匹配。
- 在搜索过程中会为回填票证提供优先级。这可使玩家群不那么支离破碎。
合约
- 可以使用字段创建 ServerDetails 回填票证。这可使服务器指示匹配的玩家应如何连接到它。
- 可以使用团队分配创建回填票证。这样具有团队的游戏可以维护其团队信息。
队列属性
- 回填票证不会触发多人游戏服务器分配。
- 回填票证不会反映在队列统计信息中，因为其玩家已经在玩游戏，并且会不准确地扭曲等待时间。
所有权
- 回填票证由游戏服务器所有，而不是用户。用户无法以任何方式查看回填票证或与之交互。

创建服务器回填票证

创建回填票证以类似于创建常规匹配票证的方式开始，但使用 CreateServerBackfillTicket 调用，而不是 CreateServerMatchmakingTicket 调用。游戏服务器必须提供当前托管的游戏的所有成员信息。执行此操作的最有效方式是存储先前匹配结果中返回的属性。通过调用具有 ReturnMemberAttributes 标志的 GetMatch 可以检索这些属性。或者，游戏服务器可以查询用户的属性信息。

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

ServerDetails

该结构与 GetMatch 调用中返回的结构相同，可供服务器指定连接到它所需的任何信息。匹配回填票证时，其 ServerDetails 结构将返回到对生成的匹配调用 GetMatch 的任何玩家。该结构中的所有字段均为可选字段。游戏可能只需要其中的一部分，以便为客户端提供足够的信息来连接到游戏服务器。

注意

字段IPV4Address未验证，可用于向客户端提供任意连接字符串信息。

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

团队分配

如果将回填票证提交到团队的队列，则每个成员也可能使用 TeamId 指定，以指示他们当前所属的团队。返回 Match 时会保留此成员身份。如果未为用户指定 TeamId，则它可以放置在任何团队中。

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

与回填票证进行交互

创建后，回填票证开始搜索符合规则条件的常规匹配票证。回填票证的流程与常规匹配票证的作方式相同，但使用类似的 API 除外。游戏服务器通过调用 GetServerBackfillTicket 可检查其票证的状态。也可通过调用 CancelServerBackfillTicket 取消票证。

注意

不允许客户端取消它们所在的回填票证。假设某个客户端正在参加 4v4 比赛，对方团队的一个玩家掉线了。客户端可以通过持续取消其所使用的任何回填票证来保持其优势。为防止这种情况，只有游戏服务器可取消回填票证。

会员资格限制以及从丢失的回填票证中恢复

与常规匹配票证类似，对于每个队列，任何时候一个用户都只能在一个回填票证中。此限制是通过独立于客户端控制的常规票证加以跟踪的。

如果游戏服务器创建回填票证后崩溃，由于会员资格限制，无法使用另一回填票证提交丢失的回填票证中的任何用户。游戏服务器通过接收错误 MatchmakingTicketMembershipLimitExceeded来发现此问题，以及指示哪些用户具有未完成的回填票证的 errorDetails 正文。

{
    "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 移除该用户所在的所有回填票证，从而从这种情况中恢复用户。此外还提供了 ListServerBackfillTicketsForPlayer，作为发现玩家可能位于哪些回填票证中的方法。

与区域选择规则的交互

区域选择规则通常要求票证指定对其属性的一系列延迟度量。但回填票证代表在特定数据中心中已经在进行的游戏。创建的请求必须在 ServerDetails 结构中指定 Region，而不是延迟度量数组。为使票证与回填票证相匹配，它们必须具有到达回填票证指定区域的可接受 ping 时间。

与团队票证大小相似性规则的交互

团队票证大小相似性规则强制使大型玩家组与其他大型玩家组进行匹配。但是，回填票证不包含哪些玩家作为一个组加入游戏的信息。因此，在匹配回填票证时，将忽略票证大小相似性规则。

通过