本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 將玩家閘道整合至遊戲
<a name="ddos-protection-integrate"></a>

建立已啟用玩家閘道的機群後，您必須更新遊戲用戶端和遊戲後端，才能與玩家閘道整合。您的遊戲後端會擷取轉送端點和玩家閘道字符，然後將它們提供給遊戲用戶端。遊戲用戶端會將所有 UDP 流量傳送至這些轉送端點。

整合遵循此呼叫路徑：

1. 您的遊戲後端會呼叫 `GetPlayerConnectionDetails` API，以擷取遊戲工作階段中每個玩家的轉送端點和玩家閘道字符。

1. 您的遊戲後端會將轉送端點和玩家閘道字符傳送至遊戲用戶端。

1. 您的遊戲用戶端會在玩家閘道字符前面加上所有傳出 UDP 封包，並將封包傳送至轉送端點。

1. 轉送網路會驗證玩家閘道字符，並將流量路由到您的遊戲伺服器。

1. 您的遊戲伺服器會透過相同的轉送路徑將流量傳回至您的遊戲用戶端。

## 後端整合
<a name="ddos-protection-integrate-backend"></a>

您的遊戲後端必須呼叫 `GetPlayerConnectionDetails` API 來擷取玩家的轉送端點和玩家閘道字符。後端接著會將此資訊提供給遊戲用戶端。

### GetPlayerConnectionDetails API
<a name="ddos-protection-integrate-backend-api"></a>

`GetPlayerConnectionDetails` API 會傳回遊戲工作階段中玩家的連線詳細資訊：

轉送端點和字符  
在 位置中啟用並支援玩家閘道時， 會傳回：  
+ **轉送端點** – 不同玩家的多個轉送端點 (IP 地址和連接埠）
+ **玩家閘道字符** – 用戶端必須附加到所有 UDP 封包的字符 （有效期至少 3 分鐘）
+ **過期** – 玩家閘道字符過期時間戳記

直接連線  
當位置中未啟用或不支援玩家閘道時， 會傳回遊戲伺服器的 IP 地址和連接埠

您的遊戲用戶端應設計為處理這兩種連線類型。

API 呼叫範例：

```
// C++ example using AWS SDK
Aws::GameLift::GameLiftClient client;
Aws::GameLift::Model::GetPlayerConnectionDetailsRequest request;
request.SetGameSessionId(gameSessionId);
request.SetPlayerIds(playerIds);  // Vector of player IDs

auto outcome = client.GetPlayerConnectionDetails(request);
if (outcome.IsSuccess()) {
    auto result = outcome.GetResult();
    auto connectionDetails = result.GetPlayerConnectionDetails();
    
    // Process each player's connection details
    for (const auto& detail : connectionDetails) {
        std::string playerId = detail.GetPlayerId();
        
        // Get relay endpoints (IP address and port)
        auto endpoints = detail.GetEndpoints();
        for (const auto& endpoint : endpoints) {
            std::string ipAddress = endpoint.GetIpAddress();
            int port = endpoint.GetPort();
        }
        
        // Get player gateway token
        auto token = detail.GetPlayerGatewayToken();
        
        // Get expiration time
        auto expiration = detail.GetExpiration();
        
        // Send endpoints and token to game client
    }
}
```

請參閱 *Amazon GameLift Servers API 參考*中的 [GetPlayerConnectionDetails](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_GetPlayerConnectionDetails.html)。

### 重新整理轉送端點
<a name="ddos-protection-integrate-backend-refresh"></a>

`GetPlayerConnectionDetails` 定期呼叫 ，以在轉送端點運作狀態不佳時為玩家提供更新的端點。我們建議遊戲工作階段中的所有玩家每 60 秒呼叫 API。若要最佳化 API 用量，請在單一 API 呼叫中批次處理多個玩家 IDs。

**重要**  
定期重新整理呼叫是將更新後的端點交付給玩家的主要機制。雖然玩家閘道字符至少保持 3 分鐘有效，但每 60 秒重新整理一次可確保玩家定期收到更新的端點。

## 用戶端整合
<a name="ddos-protection-integrate-client"></a>

您的遊戲用戶端必須在所有傳出 UDP 封包前面加上玩家閘道字符，並將封包傳送至提供的轉送端點。適用於 C\$1\$1 和 Unreal Engine 的Amazon GameLift Servers用戶端 SDK 提供公用程式來簡化此整合。

### 用戶端需求
<a name="ddos-protection-integrate-client-requirements"></a>

若要透過玩家閘道路由流量，您的遊戲用戶端必須：
+ **前綴玩家閘道字符** – 前綴玩家閘道字符到所有傳出 UDP 封包。玩家閘道字符不得加密，且必須出現在每個封包的開頭。沒有有效玩家閘道字符的封包將被捨棄。
+ **傳送至轉送端點** – 將所有 UDP 封包傳送至提供的轉送端點。
+ **維護連線活動** – 確保遊戲用戶端將封包傳送至遊戲伺服器，或遊戲伺服器將封包傳送至玩家，至少每 30 秒一次。此活動會透過轉送網路維持連線。
+ **處理端點更新** – 從後端接受更新的轉送端點和玩家閘道字符 （建議每 60 秒），並轉換到新的端點，而不捨棄連線。

### 用戶端 SDK
<a name="ddos-protection-integrate-client-sdk"></a>

適用於 C\$1\$1 和 Unreal Engine 的Amazon GameLift Servers用戶端 SDK 提供公用程式，可簡化玩家閘道整合：
+ **權杖管理** – 將玩家閘道權杖附加到所有傳出的 UDP 封包。
+ **端點選擇** – 使用可設定的演算法路由流量來轉送端點。
+ **端點重新整理** – 排程定期回呼，從後端擷取更新的轉送端點和玩家閘道字符。

### 端點選取演算法
<a name="ddos-protection-integrate-client-algorithms"></a>

用戶端 SDK 提供兩種內建演算法，用於選擇要使用的轉送端點：

備用演算法  
使用一個端點，直到運作狀態不佳，然後切換到另一個端點。最適合可接受短暫中斷的選單、大廳和輪換遊戲。在端點容錯移轉期間，封包可能會在設定的逾時期間內遺失 （預設值：2 秒）。

預測輪換演算法  
持續輪換所有可用的端點，並在故障發生之前預測故障。最適合即時遊戲，例如第一人稱射擊手和競賽遊戲，其中一致的封包交付至關重要。要求遊戲伺服器以一致的頻率傳送訊息。

您也可以擴展 SDK 的基礎演算法類別來實作自訂演算法。

### 用戶端 SDK 資源
<a name="ddos-protection-integrate-client-resources"></a>

如需完整的整合說明和範例程式碼，請參閱下列資源：

C\$1\$1  
適用於 C\$1\$1 的用戶端 SDK 可在適用於 [Amazon GameLift Servers C\$1\$1 的用戶端 SDK](https://github.com/amazon-gamelift/amazon-gamelift-servers-client-sdk-for-cpp) 取得。

虛擬引擎  
Unreal Engine 的外掛程式可在[Amazon GameLift Servers適用於 Unreal Engine 的用戶端 SDK](https://github.com/amazon-gamelift-for-unreal/amazon-gamelift-servers-client-sdk-for-unreal) 上取得。存取需要 GitHub 上 Epic Games 組織中的成員資格。如需詳細資訊，請參閱 [ GitHub 上的 Unreal Engine](https://www.unrealengine.com/en-US/ue-on-github)。

## 測試您的整合
<a name="ddos-protection-integrate-testing"></a>

在部署到機群之前，請使用玩家閘道測試工具在本機測試您的玩家閘道整合。此工具會模擬玩家閘道 UDP 代理基礎設施，並協助您驗證遊戲用戶端是否正確地加上玩家閘道字符、透過多個端點路由流量，以及處理網路降級。

如需設定和使用說明，請參閱 GitHub 上的[玩家閘道測試應用程式](https://github.com/amazon-gamelift/amazon-gamelift-toolkit/tree/main/player-gateway-testing-app)。

## 最佳實務
<a name="ddos-protection-integrate-best-practices"></a>

整合玩家閘道時，請遵循下列最佳實務：
+ **每 60 秒重新整理端點** – `GetPlayerConnectionDetails`每 60 秒呼叫一次，以確保玩家定期收到更新的端點。
+ **批次 API 呼叫** – `GetPlayerConnectionDetails`為同一遊戲工作階段中的多個玩家呼叫時，請將呼叫批次在一起，以減少 API 額外負荷。
+ **維護連線活動** – 確保至少每 30 秒在遊戲用戶端和遊戲伺服器之間流動一次流量。這可以是client-to-server或server-to-client流量。
+ **正常處理端點更新** – 當您的遊戲用戶端從後端接收更新後的端點時，請轉換至新的端點，而不會捨棄玩家的連線。
+ **選擇正確的演算法**：選取最符合您遊戲需求的端點選取演算法。針對輪換型遊戲使用備用演算法，針對即時遊戲使用預測輪換演算法。