本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 適用於 Amazon GameLift Servers 4.x 的 C\# 伺服器 SDK -- 動作使用伺服器 SDK 參考來整合多玩家遊戲，以便與進行託管Amazon GameLift Servers。如需整合程序的指引，請參閱 [使用伺服器 SDK 將 Amazon GameLift Servers新增至您的遊戲伺服器](gamelift-sdk-server-api.md)。 **注意** 此參考適用於的舊版伺服器 SDKAmazon GameLift Servers。如需最新版本，請參閱[適用於 -- 動作的 C\# 伺服器 SDK Amazon GameLift Servers 5.x](integration-server-sdk5-csharp-actions.md)。 [適用於 Amazon GameLift Servers 4.x 的 C\# 伺服器 SDK -- 資料類型](integration-server-sdk-csharp-ref-datatypes.md) **Topics** + [適用於 Amazon GameLift Servers 4.x 的 C\# 伺服器 SDK -- 資料類型](integration-server-sdk-csharp-ref-datatypes.md) + [AcceptPlayerSession()](#integration-server-sdk-csharp-ref-acceptplayersession) + [ActivateGameSession()](#integration-server-sdk-csharp-ref-activategamesession) + [DescribePlayerSessions()](#integration-server-sdk-csharp-ref-describeplayersessions) + [GetGameSessionId()](#integration-server-sdk-csharp-ref-getgamesessionid) + [GetInstanceCertificate()](#integration-server-sdk-csharp-ref-getinstancecertificate) + [GetSdkVersion()](#integration-server-sdk-csharp-ref-getsdk) + [GetTerminationTime()](#integration-server-sdk-csharp-ref-getterm) + [InitSDK()](#integration-server-sdk-csharp-ref-initsdk) + [ProcessEnding()](#integration-server-sdk-csharp-ref-processending) + [ProcessReady()](#integration-server-sdk-csharp-ref-processready) + [RemovePlayerSession()](#integration-server-sdk-csharp-ref-removeplayersession) + [StartMatchBackfill()](#integration-server-sdk-csharp-ref-startmatchbackfill) + [StopMatchBackfill()](#integration-server-sdk-csharp-ref-stopmatchbackfill) + [TerminateGameSession()](#integration-server-sdk-csharp-ref-terminategamesession) + [UpdatePlayerSessionCreationPolicy()](#integration-server-sdk-csharp-ref-updateplayersessioncreationpolicy) ## AcceptPlayerSession() 通知Amazon GameLift Servers服務，具有指定玩家工作階段 ID 的玩家已連線到伺服器程序，且需要驗證。 Amazon GameLift Servers 會驗證玩家工作階段 ID 是否有效，也就是玩家 ID 在遊戲工作階段中已預留玩家位置。經過驗證後，Amazon GameLift Servers 會將玩家位置的狀態從 RESERVED (已預留) 變更為 ACTIVE (使用中)。 ### 語法 ``` GenericOutcome AcceptPlayerSession(String playerSessionId) ``` ### Parameters **playerSessionId** 建立新玩家工作階段Amazon GameLift Servers時由發出的唯一 ID。物件中會指定玩家工作階段 ID`PlayerSession`，以回應用戶端對 *GameLift API* 動作 [ StartGameSessionPlacement](https://docs.aws.amazon.com/gamelift/latest/apireference/API_StartGameSessionPlacement.html)、[CreateGameSession](https://docs.aws.amazon.com/gamelift/latest/apireference/API_CreateGameSession.html)、[DescribeGameSessionPlacement](https://docs.aws.amazon.com/gamelift/latest/apireference/API_DescribeGameSessionPlacement.html) 或 [ DescribePlayerSessions](https://docs.aws.amazon.com/gamelift/latest/apireference/API_DescribePlayerSessions.html) 的呼叫。類型：字串必要：是 ### 傳回值傳回一般結果，其中包含成功或失敗以及錯誤訊息。 ### 範例此範例展示了用來處理連線請求的函數，其處理過程包括驗證和拒絕無效的玩家工作階段 ID。 ``` void ReceiveConnectingPlayerSessionID (Connection connection, String playerSessionId){ var acceptPlayerSessionOutcome = GameLiftServerAPI.AcceptPlayerSession(playerSessionId); if(acceptPlayerSessionOutcome.Success) { connectionToSessionMap.emplace(connection, playerSessionId); connection.Accept(); } else { connection.Reject(acceptPlayerSessionOutcome.Error.ErrorMessage); } } ``` ## ActivateGameSession() 通知 Amazon GameLift Servers 服務，伺服器程序已啟動遊戲工作階段，目前已準備好接受玩家連線。此動作應當做 `onStartGameSession()` 回呼函數的一部分，在所有遊戲工作階段初始化完成後進行。 ### 語法 ``` GenericOutcome ActivateGameSession() ``` ### Parameters 此動作沒有參數。 ### 傳回值傳回一般結果，其中包含成功或失敗以及錯誤訊息。 ### 範例此範例顯示的是做為 `onStartGameSession()` 委派函式一部分的 `ActivateGameSession()` 受到呼叫。 ``` void OnStartGameSession(GameSession gameSession) { // game-specific tasks when starting a new game session, such as loading map // When ready to receive players var activateGameSessionOutcome = GameLiftServerAPI.ActivateGameSession(); } ``` ## DescribePlayerSessions() 擷取玩家工作階段資料，包括設定、工作階段中繼資料和玩家資料。使用此動作可取得單一玩家工作階段資訊、一個遊戲工作階段中所有玩家工作階段的資訊，或是與單一玩家 ID 關聯的所有玩家工作階段資訊。 ### 語法 ``` DescribePlayerSessionsOutcome DescribePlayerSessions(DescribePlayerSessionsRequest describePlayerSessionsRequest) ``` ### Parameters **describePlayerSessionsRequest** [DescribePlayerSessionsRequest](integration-server-sdk-csharp-ref-datatypes.md#integration-server-sdk-csharp-ref-dataypes-playersessions) 物件描述的是要擷取哪個玩家工作階段。必要：是 ### 傳回值如果成功，會傳回 `DescribePlayerSessionsOutcome` 物件，內含一組與請求參數相符的玩家工作階段物件。玩家工作階段物件的結構與 AWS SDK Amazon GameLift Servers API [PlayerSession](https://docs.aws.amazon.com/gamelift/latest/apireference/API_PlayerSession.html) 資料類型相同。 ### 範例此範例展示了讓所有玩家工作階段均主動連線至指定之遊戲工作階段的請求。省略 *NextToken*，並將 *Limit* 的值設定為 10 時，Amazon GameLift Servers 即會傳回前 10 組符合請求的玩家工作階段記錄。 ``` // Set request parameters var describePlayerSessionsRequest = new Aws.GameLift.Server.Model.DescribePlayerSessionsRequest() { GameSessionId = GameLiftServerAPI.GetGameSessionId().Result, //gets the ID for the current game session Limit = 10, PlayerSessionStatusFilter = PlayerSessionStatusMapper.GetNameForPlayerSessionStatus(PlayerSessionStatus.ACTIVE) }; // Call DescribePlayerSessions Aws::GameLift::DescribePlayerSessionsOutcome playerSessionsOutcome = Aws::GameLift::Server::Model::DescribePlayerSessions(describePlayerSessionRequest); ``` ## GetGameSessionId() 若伺服器流程正在運作，擷取目前正在由伺服器程序託管的遊戲工作階段 ID。對於尚未透過遊戲工作階段啟用的閒置程序，呼叫會傳回 `Success`= `True`和 `GameSessionId`=`""` （空字串）。 ### 語法 ``` AwsStringOutcome GetGameSessionId() ``` ### Parameters 此動作沒有參數。 ### 傳回值如果成功，則會把遊戲工作階段 ID 當成 `AwsStringOutcome` 物件傳回。如果不成功，則會傳回錯誤訊息。 ### 範例 ``` var getGameSessionIdOutcome = GameLiftServerAPI.GetGameSessionId(); ``` ## GetInstanceCertificate() 擷取與機群及其執行個體相關聯的 pem 編碼 TLS 憑證的檔案位置。當您建立憑證組態設為 GENERATED 的新機群時， AWS Certificate Manager 會產生此憑證。使用此憑證可與遊戲用戶端建立安全連線，以及加密用戶端/伺服器通訊。 ### 語法 ``` GetInstanceCertificateOutcome GetInstanceCertificate(); ``` ### Parameters 此動作沒有參數。 ### 傳回值如果成功，會傳回`GetInstanceCertificateOutcome`物件，其中包含存放在執行個體上的機群 TLS 憑證檔案和憑證鏈的位置。從憑證鏈擷取的根憑證檔案也會存放在執行個體上。如果不成功，則會傳回錯誤訊息。如需憑證和憑證鏈資料的詳細資訊，請參閱 AWS Certificate Manager API 參考中的 [GetCertificate 回應元素](https://docs.aws.amazon.com/acm/latest/APIReference/API_GetCertificate.html#API_GetCertificate_ResponseElements)。 ### 範例 ``` var getInstanceCertificateOutcome = GameLiftServerAPI.GetInstanceCertificate(); ``` ## GetSdkVersion() 傳回內建至伺服器程序的目前開發套件版本編號。 ### 語法 ``` AwsStringOutcome GetSdkVersion() ``` ### Parameters 此動作沒有參數。 ### 傳回值如果成功，將目前開發套件版本以 `AwsStringOutcome` 物件傳回。傳回的字串僅包含版本編號（例如 "3.1.5")。如果不成功，則會傳回錯誤訊息。 ### 範例 ``` var getSdkVersionOutcome = GameLiftServerAPI.GetSdkVersion(); ``` ## GetTerminationTime() 若設有終止時間，即傳回伺服器程序排定關閉的時間。伺服器程序在收到 Amazon GameLift Servers服務的回`onProcessTerminate()`呼後會採取此動作。 Amazon GameLift Servers可能會`onProcessTerminate()`因為下列原因而呼叫：(1) 運作狀態不佳（伺服器程序已回報連接埠運作狀態或尚未回應 Amazon GameLift Servers、(2) 在縮減規模事件期間終止執行個體時，或 (3) 執行個體因 [spot-instance 中斷](spot-tasks.md)而終止時。如果程序已收到回`onProcessTerminate()`呼，則傳回的值為預估的終止時間。如果程序尚未收到回`onProcessTerminate()`呼，則會傳回錯誤訊息。進一步了解[關閉伺服器處理程序](gamelift-sdk-server-api.md#gamelift-sdk-server-terminate)的相關資訊。 ### 語法 ``` AwsDateTimeOutcome GetTerminationTime() ``` ### Parameters 此動作沒有參數。 ### 傳回值如果成功，會將終止時間傳回為 `AwsDateTimeOutcome` 物件。該值是終止時間，以自 0001 00：00：00 起已經過的刻度表示。例如，日期時間值 2020-09-13 12：26：40 -000Z 等於 637355968000000000 個刻度。如果沒有可用的終止時間，會傳回錯誤訊息。 ### 範例 ``` var getTerminationTimeOutcome = GameLiftServerAPI.GetTerminationTime(); ``` ## InitSDK() 初始化 Amazon GameLift Servers 開發套件。您應在啟動時隨即呼叫此方法，以避免系統先進行任何其他與 Amazon GameLift Servers 相關的初始化程序。 ### 語法 ``` InitSDKOutcome InitSDK() ``` ### Parameters 此動作沒有參數。 ### 傳回值如果成功，會傳回 InitSdkOutcome 物件，代表伺服器程序已準備好呼叫 [ProcessReady()](#integration-server-sdk-csharp-ref-processready)。 ### 範例 ``` var initSDKOutcome = GameLiftServerAPI.InitSDK(); ``` ## ProcessEnding() 若伺服器程序正在關閉中，則此動作會通知 Amazon GameLift Servers 服務。此方法應於所有其他清除作業 (包括關閉所有作用中遊戲工作階段) 之後呼叫。此方法應以結束代碼 0 結束，非零的結束代碼會導致該程序未徹底結束的事件訊息出現。一旦方法以代碼 0 結束，您就可以以成功的結束代碼終止程序。您也可以使用錯誤碼結束程序。如果您使用錯誤代碼結束，機群事件將指出程序異常終止 (`SERVER_PROCESS_TERMINATED_UNHEALTHY`)。 ### 語法 ``` GenericOutcome ProcessEnding() ``` ### Parameters 此動作沒有參數。 ### 傳回值傳回一般結果，其中包含成功或失敗以及錯誤訊息。 ### 範例 ``` var processEndingOutcome = GameLiftServerAPI.ProcessEnding(); if (processReadyOutcome.Success) Environment.Exit(0); // otherwise, exit with error code Environment.Exit(errorCode); ``` ## ProcessReady() 若伺服器程序已準備好託管遊戲工作階段，則此動作會通知 Amazon GameLift Servers 服務。在成功叫用[InitSDK()](#integration-server-sdk-csharp-ref-initsdk)並完成伺服器程序可託管遊戲工作階段之前所需的設定任務之後，呼叫此方法。每個程序只能呼叫此方法一次。 ### 語法 ``` GenericOutcome ProcessReady(ProcessParameters processParameters) ``` ### Parameters **processParameters** [ProcessParameters](integration-server-sdk-csharp-ref-datatypes.md#integration-server-sdk-csharp-ref-dataypes-process) 物件會傳達以下有關伺服器程序的資訊： + 在遊戲伺服器程式碼中實作的回呼方法名稱，可供 Amazon GameLift Servers 服務呼叫以與伺服器程序通訊。 + 伺服器程序正在接聽的埠號。 + 任何要 Amazon GameLift Servers 擷取並存放的遊戲工作階段特定檔案路徑。必要：是 ### 傳回值傳回一般結果，其中包含成功或失敗以及錯誤訊息。 ### 範例此範例會說明 [ProcessReady()](#integration-server-sdk-csharp-ref-processready) 呼叫和委派函數的實作。 ``` // Set parameters and call ProcessReady var processParams = new ProcessParameters( this.OnGameSession, this.OnProcessTerminate, this.OnHealthCheck, this.OnGameSessionUpdate, port, new LogParameters(new List() // Examples of log and error files written by the game server { "C:\\game\\logs", "C:\\game\\error" }) ); var processReadyOutcome = GameLiftServerAPI.ProcessReady(processParams); // Implement callback functions void OnGameSession(GameSession gameSession) { // game-specific tasks when starting a new game session, such as loading map // When ready to receive players var activateGameSessionOutcome = GameLiftServerAPI.ActivateGameSession(); } void OnProcessTerminate() { // game-specific tasks required to gracefully shut down a game session, // such as notifying players, preserving game state data, and other cleanup var ProcessEndingOutcome = GameLiftServerAPI.ProcessEnding(); } bool OnHealthCheck() { bool isHealthy; // complete health evaluation within 60 seconds and set health return isHealthy; } ``` ## RemovePlayerSession() 若具有指定玩家工作階段 ID 的玩家已與伺服器程序中斷連線，則此動作會通知 Amazon GameLift Servers 服務。Amazon GameLift Servers 會對此做出回應，將玩家位置變更為可用，使該位置可指派給新玩家。 ### 語法 ``` GenericOutcome RemovePlayerSession(String playerSessionId) ``` ### Parameters **playerSessionId** 建立新玩家工作階段Amazon GameLift Servers時由發出的唯一 ID。物件中會指定玩家工作階段 ID`PlayerSession`，以回應用戶端對 *GameLift API* 動作 [ StartGameSessionPlacement](https://docs.aws.amazon.com/gamelift/latest/apireference/API_StartGameSessionPlacement.html)、[CreateGameSession](https://docs.aws.amazon.com/gamelift/latest/apireference/API_CreateGameSession.html)、[DescribeGameSessionPlacement](https://docs.aws.amazon.com/gamelift/latest/apireference/API_DescribeGameSessionPlacement.html) 或 [ DescribePlayerSessions](https://docs.aws.amazon.com/gamelift/latest/apireference/API_DescribePlayerSessions.html) 的呼叫。類型：字串必要：是 ### 傳回值傳回一般結果，其中包含成功或失敗以及錯誤訊息。 ### 範例 ``` Aws::GameLift::GenericOutcome disconnectOutcome = Aws::GameLift::Server::RemovePlayerSession(playerSessionId); ``` ## StartMatchBackfill() 此動作會傳送請求，以便替 FlexMatch 所建立的遊戲工作階段開放空位找到新玩家。另請參閱 AWS SDK 動作 [StartMatchBackfill()](https://docs.aws.amazon.com/gamelift/latest/apireference/API_StartMatchBackfill.html)。使用此動作，目前代管遊戲工作階段的遊戲伺服器程序即可初始化配對回填請求。進一步了解[FlexMatch回填功能](https://docs.aws.amazon.com/gameliftservers/latest/flexmatchguide/match-backfill.html)。此為非同步動作。如果新玩家配對成功，Amazon GameLift Servers 服務即會使用回呼函數 `OnUpdateGameSession()` 提供更新的配對建構器資料。一個伺服器程序一次僅能有一個使用中的配對回填請求。若要發送新請求，請先呼叫 [StopMatchBackfill()](#integration-server-sdk-csharp-ref-stopmatchbackfill) 取消原始請求。 ### 語法 ``` StartMatchBackfillOutcome StartMatchBackfill (StartMatchBackfillRequest startBackfillRequest); ``` ### Parameters **StartMatchBackfillRequest** [StartMatchBackfillRequest](integration-server-sdk-csharp-ref-datatypes.md#integration-server-sdk-csharp-ref-dataypes-startmatchbackfillrequest) 物件會傳達以下資訊： + 指派給回填請求的票證 ID。此為選填的資訊，若未提供任何 ID，則 Amazon GameLift Servers 會自動產生一個。 + 傳送請求對象的配對建構器。必須填入完整的組態 ARN。此值可從遊戲工作階段的配對建構器資料中取得。 + 經回填之遊戲工作階段的 ID。 + 遊戲工作階段目前玩家可用的配對資料。必要：是 ### 傳回值傳回 StartMatchBackfillOutcome 物件，附帶配對回填票證 ID 或含有錯誤訊息的故障狀況。 ### 範例 ``` // Build a backfill request var startBackfillRequest = new AWS.GameLift.Server.Model.StartMatchBackfillRequest() { TicketId = "a ticket ID", //optional MatchmakingConfigurationArn = "the matchmaker configuration ARN", GameSessionId = GameLiftServerAPI.GetGameSessionId().Result, // gets ID for current game session //get player data for all currently connected players MatchmakerData matchmakerData = MatchmakerData.FromJson(gameSession.MatchmakerData); // gets matchmaker data for current players // get matchmakerData.Players // remove data for players who are no longer connected Players = ListOfPlayersRemainingInTheGame }; // Send backfill request var startBackfillOutcome = GameLiftServerAPI.StartMatchBackfill(startBackfillRequest); // Implement callback function for backfill void OnUpdateGameSession(GameSession myGameSession) { // game-specific tasks to prepare for the newly matched players and update matchmaker data as needed } ``` ## StopMatchBackfill() 取消以 [StartMatchBackfill()](#integration-server-sdk-csharp-ref-startmatchbackfill) 建立的使用中配對回填請求。另請參閱 AWS SDK 動作 [StopMatchmaking()](https://docs.aws.amazon.com/gamelift/latest/apireference/API_StopMatchmaking.html)。進一步了解[FlexMatch回填功能](https://docs.aws.amazon.com/gameliftservers/latest/flexmatchguide/match-backfill.html)。 ### 語法 ``` GenericOutcome StopMatchBackfill (StopMatchBackfillRequest stopBackfillRequest); ``` ### Parameters **StopMatchBackfillRequest** 識別配對票證的 [StopMatchBackfillRequest](integration-server-sdk-csharp-ref-datatypes.md#integration-server-sdk-csharp-ref-dataypes-stopmatchbackfillrequest) 物件，用以取消： + 已取消指派給此回填請求的票證 ID + 回填請求的傳送目標配對建構器 + 與回填請求相關的遊戲工作階段必要：是 ### 傳回值傳回一般結果，其中包含成功或失敗以及錯誤訊息。 ### 範例 ``` // Set backfill stop request parameters var stopBackfillRequest = new AWS.GameLift.Server.Model.StopMatchBackfillRequest() { TicketId = "a ticket ID", //optional, if not provided one is autogenerated MatchmakingConfigurationArn = "the matchmaker configuration ARN", //from the game session matchmaker data GameSessionId = GameLiftServerAPI.GetGameSessionId().Result //gets the ID for the current game session }; var stopBackfillOutcome = GameLiftServerAPI.StopMatchBackfillRequest(stopBackfillRequest); ``` ## TerminateGameSession() **此方法已棄用 4.0.1 版。相反地，伺服器程序應該[ProcessEnding()](#integration-server-sdk-csharp-ref-processending)在遊戲工作階段結束後呼叫。** 通知Amazon GameLift Servers服務伺服器程序已結束目前的遊戲工作階段。當伺服器程序保持作用中狀態並準備好託管新的遊戲工作階段時，就會呼叫此動作。只有在遊戲工作階段終止程序完成後，才應該呼叫它，因為它會向發出訊號Amazon GameLift Servers，表示伺服器程序可立即用於託管新的遊戲工作階段。如果伺服器程序會在遊戲工作階段停止後關閉，則不會呼叫此動作。反之，呼叫 [ProcessEnding()](#integration-server-sdk-csharp-ref-processending)以發出遊戲工作階段和伺服器程序都即將結束的訊號。 ### 語法 ``` GenericOutcome TerminateGameSession() ``` ### Parameters 此動作沒有參數。 ### 傳回值傳回一般結果，其中包含成功或失敗以及錯誤訊息。 ### 範例此範例說明遊戲工作階段結束時的伺服器程序。 ``` // game-specific tasks required to gracefully shut down a game session, // such as notifying players, preserving game state data, and other cleanup var terminateGameSessionOutcome = GameLiftServerAPI.TerminateGameSession(); var processReadyOutcome = GameLiftServerAPI.ProcessReady(processParams); ``` ## UpdatePlayerSessionCreationPolicy() 更新目前遊戲工作階段的能力，以接受新的玩家工作階段。遊戲工作階段可設定為接受或拒絕所有新的玩家工作階段。(也請參閱 [https://docs.aws.amazon.com/gamelift/latest/apireference/API_UpdateGameSession.html](https://docs.aws.amazon.com/gamelift/latest/apireference/API_UpdateGameSession.html) 服務 API 參考*之中的 Amazon GameLift ServersUpdateGameSession()* 動作)。 ### 語法 ``` GenericOutcome UpdatePlayerSessionCreationPolicy(PlayerSessionCreationPolicy playerSessionPolicy) ``` ### Parameters **newPlayerSessionPolicy** 字串值代表遊戲工作階段是否可接受新玩家。類型：[PlayerSessionCreationPolicy](https://sdk.amazonaws.com/cpp/api/LATEST/namespace_aws_1_1_game_lift_1_1_model.html#afa8a7527defe9e7ca0caebc239182c43) 列舉。有效值包含： + **ACCEPT\_ALL** – 接受所有新玩家工作階段。 + **DENY\_ALL** – 拒絕所有新玩家工作階段。必要：是 ### 傳回值傳回一般結果，其中包含成功或失敗以及錯誤訊息。 ### 範例此範例設定目前遊戲工作階段的加入政策為可接受所有玩家。 ``` var updatePlayerSessionCreationPolicyOutcomex = GameLiftServerAPI.UpdatePlayerSessionCreationPolicy(PlayerSessionCreationPolicy.ACCEPT_ALL); ```