本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 适用于 Amazon GameLift Servers 4.x 的 C\# 服务器 SDK – 操作使用服务器 SDK 参考，将要托管的多人游戏与 Amazon GameLift Servers 集成。有关集成过程的指南，请参阅[借助服务器 SDK 将 Amazon GameLift Servers 添加到游戏服务器](gamelift-sdk-server-api.md)。 **注意** 本参考适用于 Amazon GameLift Servers 服务器 SDK 的早期版本。有关最新版本，请参阅[适用于 Amazon GameLift Servers 的 C\# 服务器 SDK 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) ``` ### 参数 **playerSessionId** 创建新玩家会话时由 Amazon GameLift Servers 颁发的唯一 ID。玩家会话 ID 是在对象中指定的，该`PlayerSession`对象是为了响应客户端对 *GameLift API* 操作的调用而返回的[ StartGameSessionPlacement[ CreateGameSession](https://docs.aws.amazon.com/gamelift/latest/apireference/API_CreateGameSession.html)](https://docs.aws.amazon.com/gamelift/latest/apireference/API_StartGameSessionPlacement.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)。类型：字符串是否必需：是 ### 返回值返回由成功或失败组成的通用结果，并显示错误消息。 ### 示例此示例说明了处理连接请求的函数，包括验证和拒绝无效的玩家会话。 IDs ``` 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() ``` ### 参数此操作没有参数。 ### 返回值返回由成功或失败组成的通用结果，并显示错误消息。 ### 示例此示例显示了 `ActivateGameSession()` 作为 `onStartGameSession()` 委派函数的一部分调用。 ``` 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) ``` ### 参数 **describePlayerSessions请求** [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*并将 Limi *t* 值设置为 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() ``` ### 参数此操作没有参数。 ### 返回值如果成功，以 `AwsStringOutcome` 对象返回游戏会话 ID。如果不成功，将返回错误消息。 ### 示例 ``` var getGameSessionIdOutcome = GameLiftServerAPI.GetGameSessionId(); ``` ## GetInstanceCertificate() 检索与队列及其实例关联的 PEM 编码 TLS 证书的文件位置。 AWS Certificate Manager 当您在证书配置设置为 GENERATED 的情况下创建新队列时，将生成此证书。使用此证书可与游戏客户端建立安全连接并加密客户端/服务器通信。 ### 语法 ``` GetInstanceCertificateOutcome GetInstanceCertificate(); ``` ### 参数此操作没有参数。 ### 返回值如果成功，则返回一个 `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() ``` ### 参数此操作没有参数。 ### 返回值如果成功，返回以 `AwsStringOutcome` 对象返回当前 SDK 的版本。返回的字符串仅包含版本号 (例如：如果不成功，将返回错误消息。 ### 示例 ``` var getSdkVersionOutcome = GameLiftServerAPI.GetSdkVersion(); ``` ## GetTerminationTime() 如果终止时间可用，则返回安排服务器进程关闭的时间。服务器进程在收到来自 Amazon GameLift Servers 服务的 `onProcessTerminate()` 回调后执行此操作。Amazon GameLift Servers 可能出于以下原因调用 `onProcessTerminate()`：（1）运行状况不佳（服务器进程报告端口运行状况问题或未响应 Amazon GameLift Servers），（2）在缩减事件期间终止实例，或（3）因[竞价型实例中断](spot-tasks.md)而导致实例终止。如果该进程已收到 `onProcessTerminate()` 回调，则返回的值是估计的终止时间 (纪元秒)。如果进程未收到`onProcessTerminate()`回调，则会返回一条错误消息。了解有关[关闭服务器进程](gamelift-sdk-server-api.md#gamelift-sdk-server-terminate)的更多信息。 ### 语法 ``` AwsDateTimeOutcome GetTerminationTime() ``` ### 参数此操作没有参数。 ### 返回值如果成功，则以`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() ``` ### 参数此操作没有参数。 ### 返回值如果成功，则返回一个 InitSdkOutcome 对象，表示服务器进程已准备好调用[ProcessReady()](#integration-server-sdk-csharp-ref-processready)。 ### 示例 ``` var initSDKOutcome = GameLiftServerAPI.InitSDK(); ``` ## ProcessEnding() 通知 Amazon GameLift Servers 服务，该服务器进程正在关闭。应在所有其他清除任务 (包括关闭所有活动游戏会话) 之后调用此方法。此方法应退出，退出代码为 0；非零退出代码将导致生成一条事件消息，提示进程未完全退出。当该方法以代码为 0 退出后，您可以使用成功的退出代码终止该进程。您也可以退出，并返回错误代码。如果您退出时出现错误代码，则队列事件将指示进程异常终止（`SERVER_PROCESS_TERMINATED_UNHEALTHY`）。 ### 语法 ``` GenericOutcome ProcessEnding() ``` ### 参数此操作没有参数。 ### 返回值返回由成功或失败组成的通用结果，并显示错误消息。 ### 示例 ``` 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) ``` ### 参数 **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() 通知 Amazon GameLift Servers 服务，具有所指定玩家会话 ID 的玩家已从服务器进程断开连接。作为响应，Amazon GameLift Servers 将玩家位置更改为可用，这使得该玩家位置可以分配给新玩家。 ### 语法 ``` GenericOutcome RemovePlayerSession(String playerSessionId) ``` ### 参数 **playerSessionId** 创建新玩家会话时由 Amazon GameLift Servers 颁发的唯一 ID。玩家会话 ID 是在对象中指定的，该`PlayerSession`对象是为了响应客户端对 *GameLift API* 操作的调用而返回的[ StartGameSessionPlacement[ CreateGameSession](https://docs.aws.amazon.com/gamelift/latest/apireference/API_CreateGameSession.html)](https://docs.aws.amazon.com/gamelift/latest/apireference/API_StartGameSessionPlacement.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 创建的游戏会话中的开放位置查找新玩家。另请参阅 S AWS DK 操作 [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); ``` ### 参数 **StartMatchBackfillRequest** 一个 [StartMatchBackfillRequest](integration-server-sdk-csharp-ref-datatypes.md#integration-server-sdk-csharp-ref-dataypes-startmatchbackfillrequest) 对象，用于传递以下信息： + 要分配给回填请求的票证 ID。此信息是可选的；如果未提供任何 ID，则 Amazon GameLift Servers 将自动生成一个 ID。 + 要将请求发送到的对战构建器。需要完整的配置 ARN。可从游戏会话的对战构建器数据中获得此值。 + 正在进行回填的游戏会话的 ID。 + 游戏会话的当前玩家的可用对战数据。是否必需：是 ### 返回值返回带有匹配回填票证 ID 的 StartMatchBackfillOutcome 对象，或者返回失败并显示错误消息的对象。 ### 示例 ``` // 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) 创建的活动对战回填请求。另请参阅 S AWS DK 操作 [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); ``` ### 参数 **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() ``` ### 参数此操作没有参数。 ### 返回值返回由成功或失败组成的通用结果，并显示错误消息。 ### 示例此示例说明了游戏会话结束时的服务器进程。 ``` // 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() 更新当前游戏会话接受新玩家会话的能力。可将游戏会话设置为接受或拒绝所有新的玩家会话。（另请参阅《*Amazon GameLift Servers服务 API 参考*》中的 [UpdateGameSession()](https://docs.aws.amazon.com/gamelift/latest/apireference/API_UpdateGameSession.html) 操作）。 ### 语法 ``` GenericOutcome UpdatePlayerSessionCreationPolicy(PlayerSessionCreationPolicy playerSessionPolicy) ``` ### 参数 **newPlayerSession政策** 用于指示游戏会话是否接受新玩家的字符串值。类型：[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); ```