Skip to main content

game_servers

Creates, updates, deletes, gets or lists a game_servers resource.

Overview​

Namegame_servers
TypeResource
Idaws.gamelift.game_servers

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
claim_statusstringIndicates when an available game server has been reserved for gameplay but has not yet started hosting a game. Once it is claimed, the game server remains in CLAIMED status for a maximum of one minute. During this time, game clients connect to the game server to start the game and trigger the game server to update its utilization status. After one minute, the game server claim status reverts to null. (CLAIMED)
connection_infostringThe port and IP address that must be used to establish a client connection to the game server. (pattern: <code>^.\S.$</code>)
game_server_datastringA set of custom game server properties, formatted as a single string value. This data is passed to a game client or service when it requests information on game servers. (pattern: <code>^.\S.$</code>)
game_server_group_arnstringThe ARN identifier for the game server group where the game server is located. (pattern: <code>^arn:.:gameservergroup/[a-zA-Z0-9-.]$</code>)
game_server_group_namestringA unique identifier for the game server group where the game server is running. (pattern: <code>^[a-zA-Z0-9-.]+$</code>)
game_server_idstringA custom string that uniquely identifies the game server. Game server IDs are developer-defined and are unique across all game server groups in an Amazon Web Services account. (pattern: <code>^[a-zA-Z0-9-.]+$</code>)
instance_idstringThe unique identifier for the instance where the game server is running. This ID is available in the instance metadata. EC2 instance IDs use a 17-character format, for example: i-1234567890abcdef0. (pattern: <code>^i-[0-9a-zA-Z]{17}$</code>)
last_claim_timestring (date-time)Timestamp that indicates the last time the game server was claimed. The format is a number expressed in Unix time as milliseconds (for example "1469498468.057"). This value is used to calculate when a claimed game server's status should revert to null.
last_health_check_timestring (date-time)Timestamp that indicates the last time the game server was updated with health status. The format is a number expressed in Unix time as milliseconds (for example "1469498468.057"). After game server registration, this property is only changed when a game server update specifies a health check value.
registration_timestring (date-time)Timestamp that indicates when the game server registered. The format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
utilization_statusstringIndicates whether the game server is currently available for new games or is busy. Possible statuses include: AVAILABLE - The game server is available to be claimed. A game server that has been claimed remains in this status until it reports game hosting activity. UTILIZED - The game server is currently hosting a game session with players. (AVAILABLE, UTILIZED)

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
describe_game_serverselectregionThis API works with the following fleet types: EC2 (FleetIQ) Retrieves information for a registered game server. Information includes game server status, health check info, and the instance that the game server is running on. To retrieve game server information, specify the game server ID. If successful, the requested game server object is returned. Learn more Amazon GameLift Servers FleetIQ Guide
list_game_serversselectregionThis API works with the following fleet types: EC2 (FleetIQ) Retrieves information on all game servers that are currently active in a specified game server group. You can opt to sort the list by game server age. Use the pagination parameters to retrieve results in a set of sequential segments. Learn more Amazon GameLift Servers FleetIQ Guide
register_game_serverinsertregion, GameServerGroupName, GameServerId, InstanceIdThis API works with the following fleet types: EC2 (FleetIQ) Creates a new game server resource and notifies Amazon GameLift Servers FleetIQ that the game server is ready to host gameplay and players. This operation is called by a game server process that is running on an instance in a game server group. Registering game servers enables Amazon GameLift Servers FleetIQ to track available game servers and enables game clients and services to claim a game server for a new game session. To register a game server, identify the game server group and instance where the game server is running, and provide a unique identifier for the game server. You can also include connection and game server data. Once a game server is successfully registered, it is put in status AVAILABLE. A request to register a game server may fail if the instance it is running on is in the process of shutting down as part of instance balancing or scale-down activity. Learn more Amazon GameLift Servers FleetIQ Guide
update_game_serverupdateregion, GameServerGroupName, GameServerIdThis API works with the following fleet types: EC2 (FleetIQ) Updates information about a registered game server to help Amazon GameLift Servers FleetIQ track game server availability. This operation is called by a game server process that is running on an instance in a game server group. Use this operation to update the following types of game server information. You can make all three types of updates in the same request: To update the game server's utilization status from AVAILABLE (when the game server is available to be claimed) to UTILIZED (when the game server is currently hosting games). Identify the game server and game server group and specify the new utilization status. You can't change the status from to UTILIZED to AVAILABLE . To report health status, identify the game server and game server group and set health check to HEALTHY. If a game server does not report health status for a certain length of time, the game server is no longer considered healthy. As a result, it will be eventually deregistered from the game server group to avoid affecting utilization metrics. The best practice is to report health every 60 seconds. To change game server metadata, provide updated game server data. Once a game server is successfully updated, the relevant statuses and timestamps are updated. Learn more Amazon GameLift Servers FleetIQ Guide
deregister_game_serverdeleteregionThis API works with the following fleet types: EC2 (FleetIQ) Removes the game server from a game server group. As a result of this operation, the deregistered game server can no longer be claimed and will not be returned in a list of active game servers. To deregister a game server, specify the game server group and game server ID. If successful, this operation emits a CloudWatch event with termination timestamp and reason. Learn more Amazon GameLift Servers FleetIQ Guide
resume_game_server_groupexecregion, GameServerGroupName, ResumeActionsThis API works with the following fleet types: EC2 (FleetIQ) Reinstates activity on a game server group after it has been suspended. A game server group might be suspended by the SuspendGameServerGroup operation, or it might be suspended involuntarily due to a configuration problem. In the second case, you can manually resume activity on the group once the configuration problem has been resolved. Refer to the game server group status and status reason for more information on why group activity is suspended. To resume activity, specify a game server group ARN and the type of activity to be resumed. If successful, a GameServerGroup object is returned showing that the resumed activity is no longer listed in SuspendedActions. Learn more Amazon GameLift Servers FleetIQ Guide

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
regionstringAWS region (default: us-east-1)

SELECT examples​

This API works with the following fleet types: EC2 (FleetIQ) Retrieves information for a registered game server. Information includes game server status, health check info, and the instance that the game server is running on. To retrieve game server information, specify the game server ID. If successful, the requested game server object is returned. Learn more Amazon GameLift Servers FleetIQ Guide

SELECT
claim_status,
connection_info,
game_server_data,
game_server_group_arn,
game_server_group_name,
game_server_id,
instance_id,
last_claim_time,
last_health_check_time,
registration_time,
utilization_status
FROM aws.gamelift.game_servers
WHERE region = '{{ region }}' -- required
;

INSERT examples​

This API works with the following fleet types: EC2 (FleetIQ) Creates a new game server resource and notifies Amazon GameLift Servers FleetIQ that the game server is ready to host gameplay and players. This operation is called by a game server process that is running on an instance in a game server group. Registering game servers enables Amazon GameLift Servers FleetIQ to track available game servers and enables game clients and services to claim a game server for a new game session. To register a game server, identify the game server group and instance where the game server is running, and provide a unique identifier for the game server. You can also include connection and game server data. Once a game server is successfully registered, it is put in status AVAILABLE. A request to register a game server may fail if the instance it is running on is in the process of shutting down as part of instance balancing or scale-down activity. Learn more Amazon GameLift Servers FleetIQ Guide

INSERT INTO aws.gamelift.game_servers (
GameServerGroupName,
GameServerId,
InstanceId,
ConnectionInfo,
GameServerData,
region
)
SELECT 
'{{ GameServerGroupName }}' /* required */,
'{{ GameServerId }}' /* required */,
'{{ InstanceId }}' /* required */,
'{{ ConnectionInfo }}',
'{{ GameServerData }}',
'{{ region }}'
RETURNING
game_server
;

UPDATE examples​

This API works with the following fleet types: EC2 (FleetIQ) Updates information about a registered game server to help Amazon GameLift Servers FleetIQ track game server availability. This operation is called by a game server process that is running on an instance in a game server group. Use this operation to update the following types of game server information. You can make all three types of updates in the same request: To update the game server's utilization status from AVAILABLE (when the game server is available to be claimed) to UTILIZED (when the game server is currently hosting games). Identify the game server and game server group and specify the new utilization status. You can't change the status from to UTILIZED to AVAILABLE . To report health status, identify the game server and game server group and set health check to HEALTHY. If a game server does not report health status for a certain length of time, the game server is no longer considered healthy. As a result, it will be eventually deregistered from the game server group to avoid affecting utilization metrics. The best practice is to report health every 60 seconds. To change game server metadata, provide updated game server data. Once a game server is successfully updated, the relevant statuses and timestamps are updated. Learn more Amazon GameLift Servers FleetIQ Guide

UPDATE aws.gamelift.game_servers
SET 
GameServerGroupName = '{{ GameServerGroupName }}',
GameServerId = '{{ GameServerId }}',
GameServerData = '{{ GameServerData }}',
UtilizationStatus = '{{ UtilizationStatus }}',
HealthCheck = '{{ HealthCheck }}'
WHERE 
region = '{{ region }}' --required
AND GameServerGroupName = '{{ GameServerGroupName }}' --required
AND GameServerId = '{{ GameServerId }}' --required
RETURNING
game_server;

DELETE examples​

This API works with the following fleet types: EC2 (FleetIQ) Removes the game server from a game server group. As a result of this operation, the deregistered game server can no longer be claimed and will not be returned in a list of active game servers. To deregister a game server, specify the game server group and game server ID. If successful, this operation emits a CloudWatch event with termination timestamp and reason. Learn more Amazon GameLift Servers FleetIQ Guide

DELETE FROM aws.gamelift.game_servers
WHERE region = '{{ region }}' --required
;

Lifecycle Methods​

This API works with the following fleet types: EC2 (FleetIQ) Reinstates activity on a game server group after it has been suspended. A game server group might be suspended by the SuspendGameServerGroup operation, or it might be suspended involuntarily due to a configuration problem. In the second case, you can manually resume activity on the group once the configuration problem has been resolved. Refer to the game server group status and status reason for more information on why group activity is suspended. To resume activity, specify a game server group ARN and the type of activity to be resumed. If successful, a GameServerGroup object is returned showing that the resumed activity is no longer listed in SuspendedActions. Learn more Amazon GameLift Servers FleetIQ Guide

EXEC aws.gamelift.game_servers.resume_game_server_group 
@region='{{ region }}' --required 
@@json=
'{
"GameServerGroupName": "{{ GameServerGroupName }}", 
"ResumeActions": "{{ ResumeActions }}"
}'
;
Last updated on