本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 适用于 Amazon GameLift Servers 的 Go 服务器 SDK – 操作使用服务器 SDK 5.x 参考，将要托管的多人游戏与 Amazon GameLift Servers 集成。有关集成过程的指南，请参阅[借助服务器 SDK 将 Amazon GameLift Servers 添加到游戏服务器](gamelift-sdk-server-api.md)。 `GameLiftServerAPI.go`定义了 Go 服务器软件开发工具包操作。 [适用于 Amazon GameLift Servers 的 Go 服务器 SDK – 数据类型](integration-server-sdk-go-datatypes.md) **Topics** + [适用于 Amazon GameLift Servers 的 Go 服务器 SDK – 数据类型](integration-server-sdk-go-datatypes.md) + [GetSdkVersion()](#integration-server-sdk-go-getsdkversion) + [InitMetrics()](#integration-server-sdk-go-initmetrics) + [InitMetricsFromEnvironment()](#integration-server-sdk-go-initmetricsfromenv) + [InitSDK()](#integration-server-sdk-go-initsdk) + [ProcessReady()](#integration-server-sdk-go-processready) + [ProcessEnding()](#integration-server-sdk-go-processending) + [ActivateGameSession()](#integration-server-sdk-go-activategamesession) + [UpdatePlayerSessionCreationPolicy()](#integration-server-sdk-go-updateplayersessioncreationpolicy) + [GetGameSessionId()](#integration-server-sdk-go-getgamesessionid) + [GetTerminationTime()](#integration-server-sdk-go-getterm) + [AcceptPlayerSession()](#integration-server-sdk-go-acceptplayersession) + [RemovePlayerSession()](#integration-server-sdk-go-removeplayersession) + [DescribePlayerSessions()](#integration-server-sdk-go-describeplayersessions) + [StartMatchBackfill()](#integration-server-sdk-go-startmatchbackfill) + [StopMatchBackfill()](#integration-server-sdk-go-stopmatchbackfill) + [GetComputeCertificate()](#integration-server-sdk-go-getcomputecertificate) + [GetFleetRoleCredentials()](#integration-server-sdk-go-getfleetrolecredentials) + [Destroy](#integration-server-sdk-go-destroy) ## GetSdkVersion() 返回当前内置到服务器进程中的开发工具包的版本号。 ### 语法 ``` func GetSdkVersion() (string, error) ``` ### 返回值如果成功，返回以对象返回当前软件开发工具包的版本。返回的字符串仅包含版本号 (例如：如果不成功，将返回错误消息。 ### 示例 ``` version, err := server.GetSdkVersion() ``` ## InitMetrics() 初始化 Amazon GameLift Servers SDK 的指标收集。此方法设置指标报告，有助于监控服务器性能和运行状况。请在 [InitSDK()](#integration-server-sdk-go-initsdk) 之后、[ProcessReady()](#integration-server-sdk-go-processready) 之前调用此方法。 ### 语法 ``` func InitMetrics() error func InitMetrics(metricsParameters MetricsParameters) error ``` ### 参数 MetricsParameters （可选）用于配置指标收集的 `MetricsParameters` 对象。如果未提供，则使用默认指标配置。该 MetricsParameters结构包含以下字段： + `StatsdHost` – StatsD 服务器的主机名或 IP 地址。 + `StatsdPort` – StatsD 服务器进程的端口号。 + `CrashReporterHost` – 崩溃报告服务的主机名或 IP 地址。 + `CrashReporterPort` – 崩溃报告服务的端口号。 + `FlushIntervalMs` – 刷新指标数据的时间间隔（以毫秒为单位）。 + `MaxPacketSize` – 指标数据包的最大大小（以字节为单位）。有关 MetricsParameters 结构的更多信息，请参阅适用于 [C\# 数据类型的服务器 SDK 5.x](https://docs.aws.amazon.com/gameliftservers/latest/developerguide/integration-server-sdk5-csharp-datatypes.html)。 ### 返回值如果成功，则返回 `nil` 错误，表示指标收集已成功初始化。 ### 示例使用默认配置初始化指标： ``` err := server.InitMetrics() ``` 使用自定义配置初始化指标： ``` metricsParams := MetricsParameters{ StatsdHost: "localhost", StatsdPort: 8125, CrashReporterHost: "localhost", CrashReporterPort: 9125, FlushIntervalMs: 5000, MaxPacketSize: 1024, } err := server.InitMetrics(metricsParams) ``` ## InitMetricsFromEnvironment() 使用环境变量中的配置初始化 Amazon GameLift Servers SDK 的指标收集。此方法使用从运行时环境中派生的默认设置来设置指标报告。请在 [InitSDK()](#integration-server-sdk-go-initsdk) 之后、[ProcessReady()](#integration-server-sdk-go-processready) 之前调用此方法。 ### 语法 ``` func InitMetricsFromEnvironment() error ``` ### 返回值如果成功，则返回 `nil` 错误，表示已使用环境配置成功初始化指标收集。 ### 示例 ``` err := server.InitMetricsFromEnvironment() ``` ## InitSDK() 初始化 Amazon GameLift Servers 开发工具包。在与 Amazon GameLift Servers 相关的任何其他初始化发生之前，在启动时调用此方法。此方法在服务器和 Amazon GameLift Servers 服务之间设置通信。 ### 语法 ``` func InitSDK(params ServerParameters) error ``` ### 参数 [ServerParameters](integration-server-sdk-go-datatypes.md#integration-server-sdk-go-dataypes-serverparameters) 要在 Amazon GameLift Servers Anywhere 实例集上初始化游戏服务器，请使用以下信息构造 `ServerParameters` 对象： + WebSocket 用于连接到游戏服务器的 URL。 + 用于托管游戏服务器的进程的 ID。 + 托管游戏服务器进程的计算的 ID。 + 包含您的 Amazon GameLift Servers Anywhere 计算的 Amazon GameLift Servers 实例集的 ID。 + Amazon GameLift Servers 操作生成的授权令牌。要在 Amazon GameLift Servers 托管式 EC2 实例集上初始化游戏服务器，请构造一个不带参数的 `ServerParameters` 对象。通过此次调用，Amazon GameLift Servers 代理为您设置计算环境并自动连接到 Amazon GameLift Servers 服务。 ### 返回值如果成功，则返回`nil`错误，表示服务器进程已准备好调用[ProcessReady()](#integration-server-sdk-go-processready)。 **注意** 如果对部署到 `InitSDK()` Anywhere 队列的游戏版本调用失败，请检查创建编译资源时使用的`ServerSdkVersion`参数。您必须将此值明确设置为正在使用的服务器软件开发工具包版本。此参数的默认值为 4.x，这不兼容。要解决此问题，请创建新版本并将其部署到新队列。 ### 示例 Amazon GameLift Servers Anywhere 示例 ``` //Define the server parameters serverParameters := ServerParameters { WebSocketURL: "wss://us-west-1.api.amazongamelift.com", ProcessID: "PID1234", HostID: "HardwareAnywhere", FleetID: "aarn:aws:gamelift:us-west-1:111122223333:fleet/fleet-9999ffff-88ee-77dd-66cc-5555bbbb44aa", AuthToken: "1111aaaa-22bb-33cc-44dd-5555eeee66ff" } //Call InitSDK to establish a local connection with the Amazon GameLift Servers Agent to enable further communication. err := server.InitSDK(serverParameters) ``` Amazon GameLift Servers 托管式 EC2 示例 ``` //Define the server parameters serverParameters := ServerParameters {} //Call InitSDK to establish a local connection with the Amazon GameLift Servers Agent to enable further communication. err := server.InitSDK(serverParameters) ``` ## ProcessReady() 通知 Amazon GameLift Servers，该服务器进程已准备好托管游戏会话。调用后调用[InitSDK()](#integration-server-sdk-go-initsdk)此方法。每个进程只能调用一次此方法。 ### 语法 ``` func ProcessReady(param ProcessParameters) error ``` ### 参数 **ProcessParameters** [ProcessParameters](integration-server-sdk-go-datatypes.md#integration-server-sdk-go-dataypes-process) 对象，用于传输有关服务器进程的以下信息： + 游戏服务器代码中实现的回调方法的名称，Amazon GameLift Servers 服务调用其与服务器进程通信。 + 服务器进程正在侦听的端口号。 + [LogParameters](integration-server-sdk-go-datatypes.md#integration-server-sdk-go-dataypes-log) 数据类型包含您希望 Amazon GameLift Servers 服务器捕获并存储的任何游戏会话特定文件的路径。 ### 返回值如果方法失败，则返回带有错误消息的错误。如果刷新成功，则返回 `nil`。 ### 示例此示例说明 [ProcessReady()](#integration-server-sdk-go-processready) 调用和委派函数实施。 ``` // Define the process parameters processParams := ProcessParameters { OnStartGameSession: gameProcess.OnStartGameSession, OnUpdateGameSession: gameProcess.OnGameSessionUpdate, OnProcessTerminate: gameProcess.OnProcessTerminate, OnHealthCheck: gameProcess.OnHealthCheck, Port: port, LogParameters: LogParameters { // logging and error example []string {"C:\\game\\logs", "C:\\game\\error"} } } err := server.ProcessReady(processParams) ``` ## ProcessEnding() 通知 Amazon GameLift Servers，该服务器进程即将终止。请在已完成所有其他清理任务（包括关闭活动游戏会话）但尚未终止进程时调用此方法。根据的结果`ProcessEnding()`，进程以成功 (0) 或错误 (-1) 退出并生成队列事件。如果进程因错误而终止，则生成的实例集事件为 `SERVER_PROCESS_TERMINATED_UNHEALTHY`。 ### 语法 ``` func ProcessEnding() error ``` ### 返回值返回 0 错误代码或定义的错误代码。 ### 示例 ``` // operations to end game sessions and the server process defer func() { err := server.ProcessEnding() server.Destroy() if err != nil { fmt.Println("ProcessEnding() failed. Error: ", err) os.Exit(-1) } else { os.Exit(0) } } ``` ## ActivateGameSession() 通知 Amazon GameLift Servers，该服务器进程已激活游戏会话，现在已准备好接收玩家连接。此操作应作为 `onStartGameSession()` 回调函数的一部分，在所有游戏会话初始化已完成之后调用。 ### 语法 ``` func ActivateGameSession() error ``` ### 返回值如果方法失败，则返回带有错误消息的错误。 ### 示例此示例显示了 `ActivateGameSession()` 作为 `onStartGameSession()` 委派函数的一部分调用。 ``` func OnStartGameSession(GameSession gameSession) { // game-specific tasks when starting a new game session, such as loading map // Activate when ready to receive players err := server.ActivateGameSession(); } ``` ## UpdatePlayerSessionCreationPolicy() 更新当前游戏会话接受新玩家会话的能力。可将游戏会话设置为接受或拒绝所有新的玩家会话。 ### 语法 ``` func UpdatePlayerSessionCreationPolicy(policy model.PlayerSessionCreationPolicy) error ``` ### 参数 **playerSessionCreation政策** 用于指示游戏会话是否接受新玩家的字符串值。有效值包括： + ACCEPT\_ALL - 接受所有新玩家会话。 + DENY\_ALL - 拒绝所有新玩家会话。 ### 返回值如果发生故障，则返回带有错误消息的错误。 ### 示例此示例将当前游戏会话的接入策略设为接受所有玩家。 ``` err := server.UpdatePlayerSessionCreationPolicy(model.AcceptAll) ``` ## GetGameSessionId() 检索当前由服务器进程托管的游戏会话的 ID (如果服务器进程处于活动状态)。 ### 语法 ``` func GetGameSessionID() (string, error) ``` ### 参数此操作没有参数。 ### 返回值如果成功，以对象返回游戏会话 ID。对于尚未通过游戏会话激活的空闲进程，该调用会返回一个空字符串和`nil`错误。 ### 示例 ``` gameSessionID, err := server.GetGameSessionID() ``` ## GetTerminationTime() 如果终止时间可用，则返回安排服务器进程关闭的时间。服务器进程在收到来自 Amazon GameLift Servers 的 `onProcessTerminate()` 回调后执行此操作。Amazon GameLift Servers 会出于以下原因调用 `onProcessTerminate()`： + 服务器进程报告运行状况不佳或未响应 Amazon GameLift Servers。 + 在缩减事件期间终止实例时。 + 当实例因竞价[型实例中断而终](spot-tasks.md)止时。 ### 语法 ``` func GetTerminationTime() (int64, error) ``` ### 返回值如果成功，则返回服务器进程计划关闭和`nil`错误终止的时间戳（以纪元秒为单位）。该值是终止时间，以经过的刻度表示。`0001 00:00:00`例如，日期时间值等`2020-09-13 12:26:40 -000Z`于`637355968000000000`刻度。如果没有可用的终止时间，将返回一条错误消息。 ### 示例 ``` terminationTime, err := server.GetTerminationTime() ``` ## AcceptPlayerSession() 通知 Amazon GameLift Servers，具有所指定玩家会话 ID 的玩家已连接到服务器进程并且需要进行验证。Amazon GameLift Servers 将验证该玩家会话 ID 是否有效。玩家会话经过验证后，Amazon GameLift Servers 会将玩家位置的状态从 `RESERVED` 更改为 `ACTIVE`。 ### 语法 ``` func AcceptPlayerSession(playerSessionID string) error ``` ### 参数 `playerSessionId` 创建新玩家会话时由 Amazon GameLift Servers 颁发的唯一 ID。 ### 返回值返回由成功或失败组成的通用结果，并显示错误消息。 ### 示例此示例处理的连接请求包括验证和拒绝无效的玩家会话。 IDs ``` func ReceiveConnectingPlayerSessionID(conn Connection, playerSessionID string) { err := server.AcceptPlayerSession(playerSessionID) if err != nil { connection.Accept() } else { connection.Reject(err.Error()) } } ``` ## RemovePlayerSession() 通知 Amazon GameLift Servers，有玩家已断开与服务器进程的连接。作为回应，Amazon GameLift Servers 会将玩家位置更改为可用。 ### 语法 ``` func RemovePlayerSession(playerSessionID string) error ``` ### 参数 **`playerSessionId`** 创建新玩家会话时由 Amazon GameLift Servers 颁发的唯一 ID。 ### 返回值返回由成功或失败组成的通用结果，并显示错误消息。 ### 示例 ``` err := server.RemovePlayerSession(playerSessionID) ``` ## DescribePlayerSessions() 检索玩家会话数据，包括设置、会话元数据和玩家数据。使用此方法获取有关以下内容的信息： + 单人游戏会话 + 游戏会话中的所有玩家会话 + 与单个玩家 ID 关联的所有玩家会话 ### 语法 ``` func DescribePlayerSessions(req request.DescribePlayerSessionsRequest) (result.DescribePlayerSessionsResult, error) { return srv.describePlayerSessions(&req) } ``` ### 参数 **[DescribePlayerSessionsRequest](integration-server-sdk-go-datatypes.md#integration-server-sdk-go-dataypes-playersessions)** `DescribePlayerSessionsRequest` 对象描述要检索的玩家会话。 ### 返回值如果成功，将返回一个 `DescribePlayerSessionsResult` 对象，包含一组与请求参数相匹配的玩家会话对象。 ### 示例此示例演示了将所有玩家会话主动连接到指定游戏会话的请求。省略*NextToken*并将 L *im* it 值设置为 10，即可Amazon GameLift Servers返回与请求匹配的前 10 个玩家会话记录。 ``` // create request describePlayerSessionsRequest := request.NewDescribePlayerSessions() describePlayerSessionsRequest.GameSessionID, _ = server.GetGameSessionID() // get ID for the current game session describePlayerSessionsRequest.Limit = 10 // return the first 10 player sessions describePlayerSessionsRequest.PlayerSessionStatusFilter = "ACTIVE" // Get all player sessions actively connected to the game session describePlayerSessionsResult, err := server.DescribePlayerSessions(describePlayerSessionsRequest) ``` ## StartMatchBackfill() 发送请求以为使用 FlexMatch 创建的游戏会话中的开放位置查找新玩家。有关更多信息，请参阅 [FlexMatch 回填功能](https://docs.aws.amazon.com/gameliftservers/latest/flexmatchguide/match-backfill.html)。此操作为异步操作。如果成功匹配了新玩家，则 Amazon GameLift Servers 会使用回调函数 `OnUpdateGameSession()` 提供更新的对战构建器数据。服务器进程每次只能具有一个活动的对战回填请求。要发送新请求，请先调用 [StopMatchBackfill()](#integration-server-sdk-go-stopmatchbackfill) 以取消原始请求。 ### 语法 ``` func StartMatchBackfill(req request.StartMatchBackfillRequest) (result.StartMatchBackfillResult, error) ``` ### 参数 **[StartMatchBackfillRequest](integration-server-sdk-go-datatypes.md#integration-server-sdk-go-dataypes-startmatchbackfillrequest)** StartMatchBackfillRequest 对象传达以下信息： + 要分配给回填请求的票证 ID。此信息是可选的；如果未提供任何 ID，则 Amazon GameLift Servers 将自动生成一个 ID。 + 要将请求发送到的对战构建器。需要完整的配置 ARN。该值位于游戏会话的对战构建器数据中。 + 要回填的游戏会话的 ID。 + 游戏会话的当前玩家的可用对战数据。 ### 返回值返回带有匹配回填票证 ID 的 StartMatchBackfillOutcome 对象或包含错误消息的失败。 ### 示例 ``` // form the request startBackfillRequest := request.NewStartMatchBackfill() startBackfillRequest.RequestID = "1111aaaa-22bb-33cc-44dd-5555eeee66ff" // optional startBackfillRequest.MatchmakingConfigurationArn = "arn:aws:gamelift:us-west-2:111122223333:matchmakingconfiguration/MyMatchmakerConfig" var matchMaker model.MatchmakerData if err := matchMaker.UnmarshalJSON([]byte(gameSession.MatchmakerData)); err != nil { return } startBackfillRequest.Players = matchMaker.Players res, err := server.StartMatchBackfill(startBackfillRequest) // Implement callback function for backfill func OnUpdateGameSession(myGameSession model.GameSession) { // game-specific tasks to prepare for the newly matched players and update matchmaker data as needed } ``` ## StopMatchBackfill() 取消活动的对战回填请求。有关更多信息，请参阅 [FlexMatch 回填功能](https://docs.aws.amazon.com/gameliftservers/latest/flexmatchguide/match-backfill.html)。 ### 语法 ``` func StopMatchBackfill(req request.StopMatchBackfillRequest) error ``` ### 参数 **[StopMatchBackfillRequest](integration-server-sdk-go-datatypes.md#integration-server-sdk-go-dataypes-stopmatchbackfillrequest)** 标识要取消的配对门票的 StopMatchBackfillRequest 对象： + 要分配给回填请求的票证 ID + 回填请求所发送到的对战构建器 + 与回填请求关联的游戏会话 ### 返回值返回由成功或失败组成的通用结果，并显示错误消息。 ### 示例 ``` stopBackfillRequest := request.NewStopMatchBackfill() // Use this function to create request stopBackfillRequest.TicketID = "1111aaaa-22bb-33cc-44dd-5555eeee66ff" stopBackfillRequest.MatchmakingConfigurationArn = "arn:aws:gamelift:us-west-2:111122223333:matchmakingconfiguration/MyMatchmakerConfig" //error err := server.StopMatchBackfill(stopBackfillRequest) ``` ## GetComputeCertificate() 检索用于加密游戏服务器和游戏客户端之间网络连接的 TLS 证书的路径。当您将计算设备注册到 Amazon GameLift Servers Anywhere 实例集时，您可以使用该证书路径。有关更多信息，请参阅 [RegisterCompute](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_RegisterCompute.html)。 ### 语法 ``` func GetComputeCertificate() (result.GetComputeCertificateResult, error) ``` ### 返回值返回包含以下内容的`GetComputeCertificateResult`对象： + CertificatePath：计算资源上 TLS 证书的路径。使用 Amazon GameLift Servers 托管式实例集时，此路径包含： + `certificate.pem`：最终用户证书。完整的证书链是`certificateChain.pem`附加到此证书的组合。 + `certificateChain.pem`：包含根证书和中间证书的证书链。 + 根证书。 + `privateKey.pem`：最终用户证书的私钥。 + ComputeName：您的计算资源的名称。 ### 示例 ``` tlsCertificate, err := server.GetFleetRoleCredentials(getFleetRoleCredentialsRequest) ``` ## GetFleetRoleCredentials() 检索您创建的用于将权限扩展 AWS 服务到Amazon GameLift Servers其他角色的服务角色证书。这些凭据允许您的游戏服务器使用您的 AWS 资源。有关更多信息，请参阅 [为 Amazon GameLift Servers 设置 IAM 服务角色](setting-up-role.md)。 ### 语法 ``` func GetFleetRoleCredentials( req request.GetFleetRoleCredentialsRequest, ) (result.GetFleetRoleCredentialsResult, error) { return srv.getFleetRoleCredentials(&req) } ``` ### 参数 [GetFleetRoleCredentialsRequest](integration-server-sdk-go-datatypes.md#integration-server-sdk-go-dataypes-getfleetrolecredentialsrequest) 角色证书，用于将有限的 AWS 资源访问权限扩展到游戏服务器。 ### 返回值返回包含以下内容的`GetFleetRoleCredentialsResult`对象： + AssumedRoleUserArn -服务角色所属用户的亚马逊资源名称 (ARN)。 + AssumedRoleId -服务角色所属用户的 ID。 + AccessKeyId -用于对您的 AWS 资源进行身份验证和提供访问权限的访问密钥 ID。 + SecretAccessKey -用于身份验证的私有访问密钥 ID。 + SessionToken -用于识别与您的 AWS 资源交互的当前活动会话的令牌。 + 过期-您的会话凭证到期之前的时间。 ### 示例 ``` // form the customer credentials request getFleetRoleCredentialsRequest := request.NewGetFleetRoleCredentials() getFleetRoleCredentialsRequest.RoleArn = "arn:aws:iam::123456789012:role/service-role/exampleGameLiftAction" credentials, err := server.GetFleetRoleCredentials(getFleetRoleCredentialsRequest) ``` ## Destroy 从内存中释放 Amazon GameLift Servers 游戏服务器 SDK。作为最佳实操，请在终止进程之后`ProcessEnding()`和之前调用此方法。如果您使用的是 Anywhere 实例集，并且没有在每次游戏会话后终止服务器进程，请先调用 `Destroy()`，再通过 `InitSDK()` 重新初始化，最后使用 `ProcessReady()` 通知 Amazon GameLift Servers 该进程已准备好托管游戏会话。 ### 语法 ``` func Destroy() error { return srv.destroy() } ``` ### 返回值如果方法失败，则返回带有错误消息的错误。 ### 示例 ``` // operations to end game sessions and the server process defer func() { err := server.ProcessEnding() server.Destroy() if err != nil { fmt.Println("ProcessEnding() failed. Error: ", err) os.Exit(-1) } else { os.Exit(0) } } ```