本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 適用於 Amazon GameLift Servers -- 動作的 Go 伺服器 SDK 使用伺服器 SDK 5.x 參考整合多玩家遊戲，以便與進行託管。 Amazon GameLift Servers如需整合程序的指引，請參閱 [使用伺服器 SDK 將 Amazon GameLift Servers新增至您的遊戲伺服器](gamelift-sdk-server-api.md)。 `GameLiftServerAPI.go` 定義 Go 伺服器 SDK 動作。 [適用於 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) ``` ### 傳回值如果成功，會以字串的形式傳回目前的 SDK 版本。傳回的字串包含版本號碼（範例 `5.0.0`)。如果不成功，會傳回錯誤訊息，例如 `common.SdkVersionDetectionFailed`。 ### 範例 ``` 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 ``` ### Parameters MetricsParameters （選用）設定指標集合的`MetricsParameters`物件。如果未提供，則會使用預設指標組態。MetricsParameters 結構包含下列欄位： + `StatsdHost` - StatsD 伺服器的主機名稱或 IP 地址。 + `StatsdPort` - StatsD 伺服器的連接埠號碼。 + `CrashReporterHost` - 損毀報告程式服務的主機名稱或 IP 地址。 + `CrashReporterPort` - 損毀報告程式服務的連接埠號碼。 + `FlushIntervalMs` - 清除指標資料的間隔，以毫秒為單位。 + `MaxPacketSize` - 指標封包的大小上限，以位元組為單位。如需 MetricsParameters 結構的詳細資訊，請參閱適用於 [C\$1 資料類型的伺服器 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 ``` ### Parameters [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)。 **注意** 如果針對部署到 Anywhere 機群的遊戲組建呼叫`InitSDK()`失敗，請檢查建立組建資源時使用的`ServerSdkVersion`參數。您必須將此值明確設定為正在使用的伺服器 SDK 版本。此參數的預設值為 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 ``` ### Parameters **ProcessParameters** [ProcessParameters](integration-server-sdk-go-datatypes.md#integration-server-sdk-go-dataypes-process) 物件會傳達伺服器程序的下列相關資訊： + 在遊戲伺服器程式碼中實作的回呼方法名稱，Amazon GameLift Servers服務會叫用這些方法來與伺服器程序通訊。 + 伺服器程序正在接聽的連接埠號碼。 + 包含Amazon GameLift Servers您要擷取和儲存之任何遊戲工作階段特定檔案路徑的[LogParameters](integration-server-sdk-go-datatypes.md#integration-server-sdk-go-dataypes-log)資料類型。 ### 傳回值如果方法失敗，則傳回包含錯誤訊息的錯誤。`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 ``` ### Parameters **playerSessionCreationPolicy** 指出遊戲工作階段是否接受新玩家的字串值。有效值包含： + **`model.AcceptAll`** – 接受所有新的玩家工作階段。 + **`model.DenyAll`** – 拒絕所有新的玩家工作階段。 ### 傳回值如果發生失敗，則傳回包含錯誤訊息的錯誤。 ### 範例此範例設定目前遊戲工作階段的加入政策為可接受所有玩家。 ``` err := server.UpdatePlayerSessionCreationPolicy(model.AcceptAll) ``` ## GetGameSessionId() 擷取作用中伺服器程序託管的遊戲工作階段 ID。 ### 語法 ``` func GetGameSessionID() (string, error) ``` ### Parameters 此動作沒有參數。 ### 傳回值如果成功，會傳回遊戲工作階段 ID 和 nil 錯誤。對於尚未透過遊戲工作階段啟用的閒置程序，呼叫會傳回空字串和`nil`錯誤。 ### 範例 ``` gameSessionID, err := server.GetGameSessionID() ``` ## GetTerminationTime() 傳回伺服器程序排程在可用終止時間時關閉的時間。伺服器程序在收到來自的回`onProcessTerminate()`呼後會採取此動作Amazon GameLift Servers。 Amazon GameLift Servers`onProcessTerminate()`會呼叫，原因如下： + 當伺服器程序回報運作狀態不佳或尚未回應時Amazon GameLift Servers。 + 在縮減規模事件期間終止執行個體時。 + 當執行個體因 [spot-instance 中斷](spot-tasks.md)而終止時。 ### 語法 ``` func GetTerminationTime() (int64, error) ``` ### 傳回值如果成功，會以 epoch 秒傳回排定關閉伺服器程序的時間戳記，並終止`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 ``` ### Parameters `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 ``` ### Parameters **`playerSessionId`** 建立新玩家工作階段Amazon GameLift Servers時由發出的唯一 ID。 ### 傳回值傳回一般結果，其中包含成功或失敗以及錯誤訊息。 ### 範例 ``` err := server.RemovePlayerSession(playerSessionID) ``` ## DescribePlayerSessions() 擷取玩家工作階段資料，其中包括設定、工作階段中繼資料和玩家資料。使用此方法取得下列相關資訊： + 單一玩家工作階段 + 遊戲工作階段中的所有玩家工作階段 + 與單一玩家 ID 相關聯的所有玩家工作階段 ### 語法 ``` func DescribePlayerSessions(req request.DescribePlayerSessionsRequest) (result.DescribePlayerSessionsResult, error) { return srv.describePlayerSessions(&req) } ``` ### Parameters **[DescribePlayerSessionsRequest](integration-server-sdk-go-datatypes.md#integration-server-sdk-go-dataypes-playersessions)** `DescribePlayerSessionsRequest` 物件描述要擷取的玩家工作階段。 ### 傳回值如果成功，會傳回`DescribePlayerSessionsResult`物件，其中包含一組符合請求參數的玩家工作階段物件。 ### 範例此範例會請求主動連線到指定遊戲工作階段的所有玩家工作階段。透過省略 *NextToken* 並將*限制*值設定為 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) ``` ### Parameters **[StartMatchBackfillRequest](integration-server-sdk-go-datatypes.md#integration-server-sdk-go-dataypes-startmatchbackfillrequest)** StartMatchBackfillRequest 物件會傳達下列資訊： + 指派給回填請求的票證 ID。此資訊是選用的；如果未提供 ID，則 Amazon GameLift Servers會產生一個 ID。 + 傳送請求對象的配對建構器。必須填入完整的組態 ARN。此值位於遊戲工作階段的配對建構器資料中。 + 要回填的遊戲工作階段 ID。 + 遊戲工作階段目前玩家的可用配對資料。 ### 傳回值傳回具有相符回填票證 ID 或失敗並顯示錯誤訊息的`StartMatchBackfillResult`物件。 ### 範例 ``` // 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 ``` ### Parameters **[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`：包含根憑證和中繼憑證的憑證鏈。 + `rootCertificate.pem`：根憑證。 + `privateKey.pem`：最終使用者憑證的私有金鑰。 + ComputeName：運算資源的名稱。 ### 範例 ``` tlsCertificate, err := server.GetFleetRoleCredentials(getFleetRoleCredentialsRequest) ``` ## GetFleetRoleCredentials() 擷取您建立的服務角色登入資料，將許可擴展至其他 AWS 服務 Amazon GameLift Servers。這些登入資料可讓您的遊戲伺服器使用您的 AWS 資源。如需詳細資訊，請參閱[設定的 IAM 服務角色 Amazon GameLift Servers](setting-up-role.md)。 ### 語法 ``` func GetFleetRoleCredentials( req request.GetFleetRoleCredentialsRequest, ) (result.GetFleetRoleCredentialsResult, error) { return srv.getFleetRoleCredentials(&req) } ``` ### Parameters [GetFleetRoleCredentialsRequest](integration-server-sdk-go-datatypes.md#integration-server-sdk-go-dataypes-getfleetrolecredentialsrequest) 角色登入資料，可將 AWS 資源的有限存取權延伸到遊戲伺服器。 ### 傳回值傳回包含下列項目的`GetFleetRoleCredentialsResult`物件： + AssumedRoleUserArn - 服務角色所屬使用者的 Amazon Resource Name (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 機群，而且沒有在每次遊戲工作階段後終止伺服器程序，請在通知程序已準備好使用託管遊戲工作階段之前，先呼叫 Amazon GameLift Servers `Destroy()`，然後`InitSDK()`重新初始化 `ProcessReady()`。 ### 語法 ``` 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) } } ```