本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# FlexMatch 新增至遊戲用戶端
本主題說明如何將FlexMatch配對功能新增至用戶端遊戲元件。
我們強烈建議您的遊戲用戶端透過後端遊戲服務提出配對請求。透過使用此受信任來源與 Amazon GameLift Servers服務進行通訊，您可以更輕鬆地防止駭客嘗試和仿造玩家資料。如果您的遊戲有工作階段目錄服務，這是處理配對請求的理想選擇。搭配FlexMatchAmazon GameLift Servers託管和獨立服務使用 時，使用後端遊戲服務來呼叫Amazon GameLift Servers服務是最佳實務。
無論您是將 FlexMatch與Amazon GameLift Servers受管託管搭配使用，還是將 作為獨立服務與另一個託管解決方案搭配使用，都需要用戶端更新。使用Amazon GameLift Servers屬於 AWS SDK 一部分的 服務 API，新增下列功能：
+ 為一或多個玩家請求配對 （必要）。根據您的配對規則集，此請求可能需要特定玩家特定的資料，包括玩家屬性和延遲。
+ 追蹤配對請求的狀態 （必要）。一般而言，此任務需要設定事件通知。
+ 請求玩家接受提議的配對 （選用）。此功能需要額外與玩家的互動，以顯示配對詳細資訊，並允許他們接受或拒絕配對。
+ 取得遊戲工作階段連線資訊並加入遊戲 （必要）。為新配對啟動遊戲工作階段後，請擷取遊戲工作階段的連線資訊，並使用它來連線至遊戲工作階段。
## 先決條件用戶端任務
您必須先執行下列任務，才能將用戶端功能新增至遊戲：
+ **將 AWS SDK 新增至您的後端服務。**您的後端服務使用 Amazon GameLift Servers API 中的功能，這是 AWS SDK 的一部分。請參閱[Amazon GameLift Servers用戶端服務的 SDKs](https://docs.aws.amazon.com/gamelift/latest/developerguide/gamelift-supported.html#gamelift-supported-clients)，進一步了解 AWS SDK 並下載最新版本。如需 API 說明和功能，請參閱 [Amazon GameLift Servers FlexMatch API 參考 (AWS SDK)](reference-awssdk-flex.md)。
+ **設定配對票證系統。**所有配對請求都必須有唯一的票證 ID。建立產生唯一票證 IDs機制，並將其指派給符合請求。票證 ID 可使用任何字串格式，最長可達 128 個字元。
+ **收集配對建構器的相關資訊。**從配對組態和規則集取得以下資訊。
+ 配對組態資源的名稱。
+ 在規則集中定義的玩家屬性清單。
+ **擷取玩家資料。**設定取得每個玩家相關資料的方法，以包含在配對請求中。您需要玩家 ID 和玩家屬性值。如果您的規則集有延遲規則，或您想要在放置遊戲工作階段時使用延遲資料，請針對玩家可能進入遊戲的每個地理位置收集延遲資料。若要取得準確的延遲測量，請使用 Amazon GameLift Servers的 UDP ping 信標。這些端點可讓您測量玩家裝置與每個潛在託管位置之間的實際 UDP 網路延遲，從而做出比使用 ICMP ping 更準確的置放決策。如需使用 UDP ping 信標測量延遲的詳細資訊，請參閱 [UDP ping 信標](https://docs.aws.amazon.com/gameliftservers/latest/developerguide/reference-udp-ping-beacons.html)。
# 為玩家請求配對
將程式碼新增至遊戲後端服務，以管理配對FlexMatch建構器的配對請求。對於FlexMatch搭配 Amazon GameLift Servers 託管使用的遊戲，以及FlexMatch做為獨立解決方案使用的遊戲，請求FlexMatch配對的程序相同。
## 若要建立配對請求：
呼叫 Amazon GameLift Servers API [StartMatchmaking](https://docs.aws.amazon.com/gamelift/latest/apireference/API_StartMatchmaking.html). 每個請求都必須包含下列資訊。
**配對建構器**
要在請求時使用的配對組態名稱。FlexMatch 會將每個請求置放在特定配對建構器的集區中，並根據配對建構器配置方式來處理請求。這包括強制執行時間限制，無論是否請求玩家接受配對，放置產生的遊戲工作階段時要使用哪個佇列等。進一步了解規則建置器和規則集：[設計FlexMatch配對建構器](match-configuration.md)。
**票證 ID**
指派給請求的唯一票證 ID。與請求相關的所有內容 (包含事件和通知) 將會參考票證 ID。
**玩家資料**
您想要為其建立配對的玩家清單。根據配對規則與延遲最低限制，如果請求中有任何玩家不符合配對規定，配對請求就絕不會加以配對。配對請求中最多可加入 10 名玩家。如果請求中有多名玩家，FlexMatch 會嘗試建立單一配對，並將所有玩家指派給同一個隊伍 (隨機選取)。如果請求包含玩家人數過多而無法全部加入其中一個配對隊伍，則請求將無法配對。舉例來說，如果您已將配對建構器設定為建立二對二配對 (兩個隊伍，每隊兩名玩家)，則您無法傳送包含超過兩名玩家的配對請求。
玩家 (由玩家 ID 加以識別) 一次僅能加入一個進行中的配對請求。當您為玩家建立了新請求，任何含有相同玩家 ID 的啟用中配對票證均會自動取消。
對於每個列出的玩家，請包含下列資料：
+ *玩家 ID *– 每個玩家都必須擁有您產生的唯一玩家 ID。請參閱[產生玩家 IDs](https://docs.aws.amazon.com/gamelift/latest/developerguide/player-sessions-player-identifiers.html)。
**重要**
當您建立新的配對請求，其中包含已包含在現有作用中配對請求中的玩家 ID 時，現有的請求會自動取消。不過，不會針對已取消的請求傳送`MatchmakingCancelled`事件。若要監控現有配對請求的狀態，請使用 [DescribeMatchmaking](https://docs.aws.amazon.com/gamelift/latest/apireference/API_DescribeMatchmaking.html) 以不常間隔輪詢請求狀態 (30-60 秒）。取消的請求會顯示 狀態`CANCELLED`，其中包含原因 `Cancelled due to duplicate player`。
+ *玩家屬性* – 如果 中的配對建構器使用 呼叫玩家屬性，則請求必須為每個玩家提供這些屬性。配對規則集會定義必要的玩家屬性，其中也會指定屬性的資料類型。只有當規則集指定屬性的預設值時，玩家屬性才會是選用的。如果配對請求未提供所有玩家的必要玩家屬性，則配對請求永遠無法成功。在[建置FlexMatch規則集](match-rulesets.md)和[FlexMatch 規則集範例](match-examples.md)中進一步了解配對建置規則集和玩家屬性。
+ *玩家延遲* – 如果使用的配對建構器具有玩家延遲規則，則請求必須報告每個玩家的延遲。玩家延遲資料是每個玩家的一或多個值的清單。其代表玩家在配對建構器佇列中區域的玩家體驗延遲。如果請求中沒有包含玩家的延遲值，則無法對玩家進行配對，請求也會失敗。若要取得準確的延遲測量，請使用 Amazon GameLift Servers的 UDP ping 信標。這些端點可讓您測量玩家裝置與潛在託管位置之間的實際 UDP 網路延遲，從而做出比使用 ICMP ping 更準確的置放決策。如需使用 UDP ping 信標測量延遲的詳細資訊，請參閱 [UDP ping 信標](https://docs.aws.amazon.com/gameliftservers/latest/developerguide/reference-udp-ping-beacons.html)。
## 擷取相符請求詳細資訊
傳送比對請求後，您可以使用請求的票證 ID 呼叫 [DescribeMatchmaking](https://docs.aws.amazon.com/gamelift/latest/apireference/API_DescribeMatchmaking.html) 來檢視請求詳細資訊。此呼叫會傳回請求資訊，包含目前的狀態。成功完成請求之後，票證也會包含遊戲用戶端連線至配對所需的資訊。
## 取消比對請求
您只要呼叫 [StopMatchmaking](https://docs.aws.amazon.com/gamelift/latest/apireference/API_StopMatchmaking.html)，即可隨時取消配對請求。
# 追蹤配對事件
設定通知以追蹤 Amazon GameLift Servers 針對配對程序發出的事件。您可以直接設定通知、建立 SNS 主題或使用 Amazon EventBridge。如需有關設定通知的詳細資訊，請參閱 [設定FlexMatch事件通知](match-notification.md)。設定好通知後，在用戶端服務上新增接聽程式，以偵測事件並依需求回應。
當一大段時間過去而完全不通知的情況下，定期輪詢狀態更新來備份通知，也是個不錯的主意。若要盡量降低對於配對效能的影響，請務必在配對單提交後至少 30 秒或最後收到通知後才進行輪詢。
使用請求的票證 ID 呼叫 [DescribeMatchmaking](https://docs.aws.amazon.com/gamelift/latest/apireference/API_DescribeMatchmaking.html)，擷取配對請求票證，其中包含目前的狀態。建議輪詢不要超過 10 秒一次。這個方法僅適用於低用量開發案例。
**注意**
在進行大量配對使用之前 (例如進行生產前負載測試)，您應該使用事件通知來設定遊戲。公開發行版本中的所有遊戲都應該使用通知，不論用量如何。持續輪詢方式只適用於開發時使用少量配對的遊戲。
# 請求玩家接受
如果您正在使用玩家已開啟接受的遊戲建置器，則將程式碼新增到您的用戶端服務，以管理玩家接受程序。對於FlexMatch搭配 Amazon GameLift Servers受管託管使用的遊戲，以及FlexMatch做為獨立解決方案使用的遊戲，管理玩家接受的程序相同。
**請求玩家接受建議配對：**
1. **當提議配對需要玩家接受時進行偵測。**當狀態變更為 `REQUIRES_ACCEPTANCE` 時，監控配對票證以進行偵測。此狀態的變更會觸發FlexMatch事件 `MatchmakingRequiresAcceptance`。
1. **獲得所有玩家接受。**建立機制，以便向每個玩家出示配對票證中的提議配對詳細資訊。玩家必須能夠表示他們接受或拒絕提議的配對。您可以呼叫 [DescribeMatchmaking](https://docs.aws.amazon.com/gamelift/latest/apireference/API_DescribeMatchmaking.html) 來擷取配對詳細資訊。玩家須在有限時間內回應，否則配對建置器會撤銷提議的配對並繼續下一步。
1. **向 FlexMatch 回報玩家回應。**呼叫 [AcceptMatch](https://docs.aws.amazon.com/gamelift/latest/apireference/API_AcceptMatch.html) 以回報玩家的回覆設定，藉此了解該玩家接受或拒絕配對。配對請求中的所有玩家均需接受配對才能繼續。
1. **處理接受失敗的票證。**當任何玩家在提議的配對中拒絕配對，或無法於接受時間限制內回覆，請求都會失敗。接受配對之玩家的門票會自動傳回至門票集區。未接受配對的玩家票證會移至失敗狀態，且不會再處理。對於有多個玩家的門票，如果門票中的任何玩家不接受配對，則整個門票會失敗。
# 連接至相符項目
將程式碼新增至您的用戶端服務，以處理成功形成的配對 （狀態`COMPLETED`或事件 `MatchmakingSucceeded`)。這包括通知配對的玩家並將連線資訊交付到其遊戲用戶端。
對於使用Amazon GameLift Servers受管託管的遊戲，當成功滿足配對請求時，遊戲工作階段連線資訊會新增至配對票證。呼叫 [DescribeMatchmaking](https://docs.aws.amazon.com/gamelift/latest/apireference/API_DescribeMatchmaking.html)，擷取完整的配對票證。連線資訊包含遊戲工作階段的 IP 地址和連接埠，以及每個玩家 ID 的玩家工作階段 ID。請至 [GameSessionConnectionInfo](https://docs.aws.amazon.com/gamelift/latest/apireference/API_GameSessionConnectionInfo.html) 進一步了解。您的遊戲用戶端可以使用此資訊直接連線至遊戲工作階段以進行配對。連線請求應包含玩家工作階段 ID 和玩家 ID。此資料會將連線的玩家與遊戲工作階段的配對資料產生關聯，其中包含團隊指派 (請參閱 [GameSession](https://docs.aws.amazon.com/gamelift/latest/apireference/API_GameSession.html))。
對於使用其他託管解決方案的遊戲，包括Amazon GameLift Servers FleetIQ，您必須建置一種機制，讓配對玩家連線到適當的遊戲工作階段。
# 配對請求範例
下列程式碼片段會為數個不同的配對建構器建置配對請求。如上所述，請求必須提供使用中配對建置器所需的玩家屬性，如同配對建置器規則集所定義。提供的屬性必須使用相同的資料類型，如規則集中定義的數字 (N) 或字串 (S)。
```
# Uses matchmaker for two-team game mode based on player skill level
def start_matchmaking_for_cowboys_vs_aliens(config_name, ticket_id, player_id, skill, team):
response = gamelift.start_matchmaking(
ConfigurationName=config_name,
Players=[{
"PlayerAttributes": {
"skill": {"N": skill}
},
"PlayerId": player_id,
"Team": team
}],
TicketId=ticket_id)
# Uses matchmaker for monster hunter game mode based on player skill level
def start_matchmaking_for_players_vs_monster(config_name, ticket_id, player_id, skill, is_monster):
response = gamelift.start_matchmaking(
ConfigurationName=config_name,
Players=[{
"PlayerAttributes": {
"skill": {"N": skill},
"desiredSkillOfMonster": {"N": skill},
"wantsToBeMonster": {"N": int(is_monster)}
},
"PlayerId": player_id
}],
TicketId=ticket_id)
# Uses matchmaker for brawler game mode with latency
def start_matchmaking_for_three_team_brawler(config_name, ticket_id, player_id, skill, role):
response = gamelift.start_matchmaking(
ConfigurationName=config_name,
Players=[{
"PlayerAttributes": {
"skill": {"N": skill},
"character": {"S": [role]},
},
"PlayerId": player_id,
"LatencyInMs": { "us-west-2": 20}
}],
TicketId=ticket_id)
# Uses matchmaker for multiple game modes and maps based on player experience
def start_matchmaking_for_multi_map(config_name, ticket_id, player_id, skill, maps, modes):
response = gamelift.start_matchmaking(
ConfigurationName=config_name,
Players=[{
"PlayerAttributes": {
"experience": {"N": skill},
"gameMode": {"SL": modes},
"mapPreference": {"SL": maps}
},
"PlayerId": player_id
}],
TicketId=ticket_id)
```