> ## 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](/zh-TW/services/playfab/multiplayer/matchmaking/backfill-tickets-multiplayer-sdk)
</Note>

裝載在伺服器上的遊戲有時會發現需要搜尋額外的玩家。最常見的情況是在遊戲進行期間有一或多位玩家中斷連線。伺服器回填票證可讓遊戲伺服器搜尋適合目前進行中遊戲的額外玩家。

伺服器回填票證與一般配對票證在多個方面有所不同：

1. 配對
   * 回填票證無法彼此配對。
   * 回填票證在搜尋期間會獲得優先權。這可減少玩家群的分散。
2. 合約
   * 建立回填票證時可以包含 `ServerDetails` 欄位。這可讓伺服器指出配對成功的玩家應如何連線到伺服器。
   * 建立回填票證時可以包含隊伍指派。這可讓有隊伍的遊戲保留其隊伍資訊。
3. 佇列屬性
   * 回填票證不會觸發 [Multiplayer Server 配置](/zh-TW/services/playfab/multiplayer/matchmaking/multiplayer-servers)。
   * 回填票證不會反映在[佇列統計資料](/zh-TW/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>
  用戶端不得取消其所在的回填票證。假設某個用戶端在 4 對 4 的比賽中，而對方隊伍有一位玩家離開。該用戶端可能會藉由持續取消其所在的任何回填票證來維持優勢。為了防止這種情況，只有遊戲伺服器可以取消回填票證。
</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) 讓使用者從此情況中復原，此呼叫會移除使用者所在的所有回填票證。另外也提供 [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) 結構中指定 Region，而不是延遲測量值陣列。票證若要與回填票證配對，必須對回填票證所指定的區域具有可接受的 Ping 時間。

## 與隊伍票證大小相似度規則的互動

隊伍票證大小相似度規則會強制讓大型玩家群組與其他大型玩家群組配對。不過，回填票證不包含哪些玩家是以群組身分加入遊戲的資訊。因此，配對回填票證時會忽略票證大小相似度規則。


## Related topics

- [使用伺服器回填票證 - Multiplayer SDK](/zh-TW/services/playfab/multiplayer/matchmaking/backfill-tickets-multiplayer-sdk.md)
- [取消伺服器回填票證](/zh-TW/services/playfab/api-references/rest/multiplayer/matchmaking/cancel-server-backfill-ticket.md)
- [取得伺服器回填票證](/zh-TW/services/playfab/api-references/rest/multiplayer/matchmaking/get-server-backfill-ticket.md)
- [建立伺服器回填票證](/zh-TW/services/playfab/api-references/rest/multiplayer/matchmaking/create-server-backfill-ticket.md)
- [列出玩家的伺服器回填票證](/zh-TW/services/playfab/api-references/rest/multiplayer/matchmaking/list-server-backfill-tickets-for-player.md)