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

# 整合Amazon GameLift Servers遊戲用戶端功能
<a name="gamelift-sdk-client-api"></a>

將Amazon GameLift Servers遊戲託管功能整合到需要與服務通訊的任何解決方案元件Amazon GameLift Servers，例如取得遊戲工作階段資訊或建立新的遊戲工作階段。在大多數情況下，此功能內建於後端服務元件中。新增核心任務的功能，包括：
+ 請求作用中遊戲工作階段的資訊和狀態。
+ 為現有遊戲工作階段中的新玩家預留位置。
+ 為一組玩家建立新的遊戲工作階段。
+ 請求配對一位或多位玩家。
+ 提供現有遊戲工作階段的更新資料。

[遊戲用戶端/伺服器與 的互動 Amazon GameLift Servers](gamelift-sdk-interactions.md) 如需遊戲託管元件如何透過 Amazon GameLift Servers SDKs互動的其他詳細資訊，請參閱 。

## 設定 Amazon GameLift Servers API
<a name="gamelift-sdk-client-api-initialize"></a>

 適用於 C\+\+ 的 AWS SDK 使用 將 Amazon GameLift Servers 新增至專案。

新增程式碼以初始化Amazon GameLift Servers用戶端和存放金鑰設定。此程式碼必須在相依於 的任何程式碼之前執行Amazon GameLift Servers。

1. 設定用戶端組態。使用預設用戶端組態或建立自訂用戶端組態物件。如需詳細資訊，請參閱 [https://sdk.amazonaws.com/cpp/api/LATEST/aws-cpp-sdk-core/html/struct_aws_1_1_client_1_1_client_configuration.html](https://sdk.amazonaws.com/cpp/api/LATEST/aws-cpp-sdk-core/html/struct_aws_1_1_client_1_1_client_configuration.html)(C\+\+) 或 [AmazonGameLiftConfig](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/GameLift/TGameLiftConfig.html) (C\#)。

   用戶端組態會指定聯絡 時要使用的目標區域和端點Amazon GameLift Servers。區域識別要使用的一組已部署資源 （機群、佇列和配對建構器）。預設用戶端組態會將位置設定為美國東部 （維吉尼亞北部） 區域。若要使用任何其他區域，請建立自訂組態。

1. 初始化 Amazon GameLift Servers 用戶端。使用 [Aws：：GameLift：：GameLiftClient()](https://sdk.amazonaws.com/cpp/api/LATEST/aws-cpp-sdk-gamelift/html/class_aws_1_1_game_lift_1_1_game_lift_client.html) (C\+\+) 或 [AmazonGameLiftClient()](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/GameLift/TGameLiftClient.html) (C\#) 搭配預設用戶端組態或自訂用戶端組態。

1. 如果您使用的是玩家工作階段，請新增機制來為每個玩家產生唯一識別符。如需詳細資訊，請參閱[產生玩家 IDs](player-sessions-player-identifiers.md)。

1. 收集並存放下列資訊：
   + **目標機群** – 如果您在特定機群上手動建立遊戲工作階段，請提供機群 ID 或指向目標機群的別名 ID。如果機群是多位置，請指定機群位置 。最佳實務是使用機群別名，讓您可以將玩家從一個機群切換到另一個機群，而無需更新您的後端服務。
   + **目標佇列** – 對於使用多機群佇列來放置新遊戲工作階段的遊戲，請指定要傳送放置請求的佇列名稱。
   + **AWS 登入**資料 – 對 的所有呼叫Amazon GameLift Servers都必須為託管遊戲的 提供登入 AWS 帳戶 資料。您可以建立玩家使用者來取得這些登入資料，如中所述[為您的遊戲設定程式設計存取](setting-up-aws-login.md#getting-started-iam-player-user)。根據您管理玩家使用者存取權的方式，請執行下列動作：
     + 如果您使用角色來管理玩家使用者許可，請在呼叫 Amazon GameLift Servers API 之前新增程式碼以擔任角色。擔任角色的請求會傳回一組臨時安全登入資料。如需詳細資訊，請參閱《[IAM 使用者指南》中的切換到 IAM 角色 (AWS API)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-api.html)。 **
     + 如果您有長期安全登入資料，請將您的程式碼設定為尋找和使用儲存的登入資料。請參閱《 *AWS SDKs和工具參考指南*》中的[使用長期憑證進行身分驗證](https://docs.aws.amazon.com/sdkref/latest/guide/access-iam-users.html)。如需儲存登入資料的資訊，請參閱 [(C\+\+)](https://sdk.amazonaws.com/cpp/api/LATEST/aws-cpp-sdk-core/html/class_aws_1_1_auth_1_1_a_w_s_credentials.html) 和 [(.NET)](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-creds.html) 的AWS API 參考。
     + 如果您有臨時安全登入資料，請新增程式碼，以使用 AWS Security Token Service (AWS STS) 定期重新整理登入資料，如 *IAM 使用者指南*中的[使用臨時安全登入資料搭配 AWS SDKs](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html#using-temp-creds-sdk) 所述。程式碼必須在舊登入資料過期之前請求新的登入資料。

## 取得作用中的遊戲工作階段
<a name="gamelift-sdk-client-api-find"></a>

新增程式碼以探索可用的遊戲工作階段，並管理遊戲工作階段設定和中繼資料。

**搜尋作用中的遊戲工作階段**

使用 [SearchGameSessions](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_SearchGameSessions.html) 取得特定遊戲工作階段、所有作用中工作階段或符合一組搜尋條件的工作階段的相關資訊。此呼叫為每個符合搜尋請求的活動遊戲工作階段傳回一個 [GameSession](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_GameSession.html) 物件。此物件包含遊戲用戶端連線到遊戲工作階段所需的 DNS 名稱、IP 地址和連接埠。

使用搜尋條件取得篩選過的列表，列出可供玩家加入的活動遊戲工作階段。例如，您可以篩選工作階段，如下所示：
+ 排除已滿的遊戲工作階段：`CurrentPlayerSessionCount = MaximumPlayerSessionCount`。
+ 根據工作階段執行的時間長度選擇遊戲工作階段：評估 `CreationTime`。
+ 根據自訂遊戲屬性尋找遊戲工作階段：`gameSessionProperties.gameMode = "brawl"`。

**管理遊戲工作階段資料**

使用以下任意一項操作來擷取或更新遊戲工作階段資訊。
+ [DescribeGameSessionDetails()](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_DescribeGameSessionDetails.html) – 取得遊戲工作階段的保護狀態，以及遊戲工作階段資訊。
+ [UpdateGameSession()](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_UpdateGameSession.html) – 視需要變更遊戲工作階段的中繼資料和設定。
+ [GetGameSessionLogUrl](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_GetGameSessionLogUrl.html) – 存取儲存的遊戲工作階段日誌。

## 建立遊戲工作階段
<a name="gamelift-sdk-client-api-create"></a>

加入用於在已部署的機群中啟動新遊戲工作階段並使其可供玩家加入的程式碼。建立遊戲工作階段有兩種選項，取決於遊戲託管解決方案管理遊戲工作階段置放的方式。

**使用多位置佇列建立遊戲工作階段**

使用 [StartGameSessionPlacement](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_StartGameSessionPlacement.html) 在佇列中放置新遊戲工作階段請求。若要使用此操作，請建立佇列。這會決定Amazon GameLift Servers放置新遊戲工作階段的位置。如需佇列及其使用方式的詳細資訊，請參閱 [設定遊戲工作階段置放](queues-intro.md)。

建立遊戲工作階段置放時，請指定要使用的佇列名稱、遊戲工作階段名稱、並行玩家數量上限，以及選用的一組遊戲屬性。您也可以選擇性地提供玩家清單，以自動加入遊戲工作階段。如果您包含相關區域的玩家延遲資料，則 Amazon GameLift Servers會使用此資訊將新的遊戲工作階段放置在機群上，為玩家提供理想的遊戲體驗。

若要取得準確的延遲測量，請使用 Amazon GameLift Servers的 UDP ping 信標。這些端點可讓您測量玩家裝置與潛在託管位置之間的實際 UDP 網路延遲，從而做出比使用 ICMP ping 更準確的置放決策。如需使用 UDP ping 信標測量延遲的詳細資訊，請參閱 [UDP Ping 指標](reference-udp-ping-beacons.md)。

遊戲工作階段放置為非同步程序。提出請求後，您可以讓請求成功或逾時。您也可以隨時使用 [StopGameSessionPlacement](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_StopGameSessionPlacement.html) 來取消請求。若要檢查置放請求的狀態，請呼叫 [DescribeGameSessionPlacement](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_DescribeGameSessionPlacement.html)。

**在特定機群上建立遊戲工作階段**

使用 [CreateGameSession](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_CreateGameSession.html) 在特定機群中建立新工作階段。這一個同步操作的成功與否取決於該機群是否擁有託管新遊戲工作階段所需的資源。在 Amazon GameLift Servers 建立新的遊戲工作階段並傳回 [GameSession](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_GameSession.html) 物件後，您可以將玩家加入其中。

當您使用此操作時，請提供機群 ID 或別名 ID、工作階段名稱，以及遊戲的並行玩家數量上限。您可以選擇包括一組遊戲屬性。遊戲屬性是在金鑰/值對的陣列中定義。

如果您使用Amazon GameLift Servers資源保護功能來限制玩家可以建立的遊戲工作階段數量，請提供遊戲工作階段建立者的玩家 ID。

## 將玩家加入遊戲工作階段
<a name="gamelift-sdk-client-api-join"></a>

新增程式碼以保留作用中遊戲工作階段中的玩家位置，並將遊戲用戶端連線至遊戲工作階段。如果您的遊戲使用具有唯一玩家 IDs玩家工作階段，即可使用此動作。如需玩家工作階段的詳細資訊，請參閱 [Amazon GameLift Servers 和玩家體驗](game-sessions-intro.md)。

1. 

**在遊戲工作階段中預留玩家位置**

   若要保留玩家位置，請為遊戲工作階段建立玩家工作階段。有兩種方式可以進行：
   + 如果您使用 [StartGameSessionPlacement](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_StartGameSessionPlacement.html) 或 [ StartMatchmaking](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_StartMatchmaking.html) 建立遊戲工作階段，您可以在請求中包含一或多個玩家，以在新的遊戲工作階段中為其建立玩家工作階段。
   + 若要將玩家新增至現有的遊戲工作階段，請使用遊戲工作階段 ID 呼叫 [CreatePlayerSession](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_CreatePlayerSession.html) 或 [CreatePlayerSessions](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_CreatePlayerSessions.html)。

   玩家工作階段請求必須包含唯一的玩家 ID。如需詳細資訊，請參閱[產生玩家 IDs](player-sessions-player-identifiers.md)。收到請求時， Amazon GameLift Servers 會驗證遊戲工作階段是否接受新的玩家，並且有可用的玩家位置。如果成功， 會為玩家Amazon GameLift Servers保留位置、建立新的玩家工作階段，並傳回 [PlayerSession](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_PlayerSession.html) 物件。

   玩家工作階段可以包含一組自訂玩家資料。此資料存放在新建立的玩家工作階段物件中。當玩家直接連線至遊戲工作階段時， 會將此物件Amazon GameLift Servers傳遞至遊戲伺服器。請求多個玩家工作階段時，請將每個玩家資料字串映射至玩家 ID。

1. 

**連線至遊戲工作階段**

   將程式碼新增至後端服務以擷取`PlayerSession`物件 （例如呼叫 [DescribePlayerSessions()](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_DescribePlayerSessions.html))，並將其傳回遊戲用戶端。此物件包含 DNS 名稱、IP 地址和連接埠。遊戲用戶端可以使用此資訊建立與伺服器的直接連線。
   + 您可以使用指定的連接埠和指派給伺服器程序的 DNS 名稱或 IP 地址進行連線。
   + 如果您的機群已啟用 TLS 憑證產生，請使用 DNS 名稱和連接埠進行連線。
   + 如果您的遊戲伺服器驗證傳入玩家連線，則參考玩家工作階段 ID。

   進行連線後，遊戲用戶端和伺服器程序會直接通訊，而不涉及 Amazon GameLift Servers。伺服器會維持與 的通訊，Amazon GameLift Servers以報告玩家連線狀態、運作狀態等。

   如果遊戲伺服器驗證傳入的玩家，則會驗證玩家工作階段 ID 是否符合遊戲工作階段中的預留位置，並接受或拒絕玩家連線。當玩家中斷連線時，伺服器程序會報告中斷的連線。

## 將自訂遊戲資料傳遞至遊戲工作階段
<a name="game-properties"></a>

您的遊戲用戶端可以將資料傳遞至遊戲工作階段。當您建立遊戲工作階段時，您可以在請求中包含一組遊戲屬性 （金鑰/值對） 或遊戲工作階段資料 （字串值）。您也可以使用新的或更新的遊戲資料來更新現有的遊戲工作階段。此資料會傳遞至託管遊戲工作階段的遊戲伺服器程序，以供遊戲伺服器程式碼使用。您無法刪除遊戲屬性。

例如，假設您的遊戲定義了難度等級：`Novice`、`Intermediate`、 `Easy`和 `Expert`。玩家選擇加入 `Easy`、 遊戲。您的遊戲用戶端透過後端服務，使用下列遊戲屬性請求新的遊戲工作階段：`{"Key": "Difficulty", "Value":"Easy"}`。作為回應， 會Amazon GameLift Servers提示可用的遊戲伺服器啟動新的遊戲工作階段並傳遞`GameSession`物件。遊戲伺服器程序使用提供的遊戲屬性來設定遊戲工作階段的難度等級。

### 進一步了解
<a name="w2aab9c13c11c17b7"></a>
+ [GameProperty 資料類型](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_GameProperty.html) 
+ [SearchGameSessions() 範例](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_SearchGameSessions.html#API_SearchGameSessions_Examples) 
+ [UpdateGameSession() GameProperties 參數](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_UpdateGameSession.html#gamelift-UpdateGameSession-request-GameProperties)