2016/03/10 - Amazon GameLift - 4 new 9 updated api methods
Creates or updates a scaling policy for a fleet. An active scaling policy prompts GameLift to track a certain metric for a fleet and automatically change the fleet's capacity in specific circumstances. Each scaling policy contains one rule statement. Fleets can have multiple scaling policies in force simultaneously.
A scaling policy rule statement has the following structure:
If [MetricName] is [ComparisonOperator] [Threshold] for [EvaluationPeriods] minutes, then [ScalingAdjustmentType] to/by [ScalingAdjustment] .
For example, this policy: "If the number of idle instances exceeds 20 for more than 15 minutes, then reduce the fleet capacity by 10 instances" could be implemented as the following rule statement:
If [IdleInstances] is [GreaterThanOrEqualToThreshold] [20] for [15] minutes, then [ChangeInCapacity] by [-10].
To create or update a scaling policy, specify a unique combination of name and fleet ID, and set the rule values. All parameters for this action are required. If successful, the policy name is returned. Scaling policies cannot be suspended or made inactive. To stop enforcing a scaling policy, call DeleteScalingPolicy.
Request Syntax
client.put_scaling_policy(
Name='string',
FleetId='string',
ScalingAdjustment=123,
ScalingAdjustmentType='ChangeInCapacity'|'ExactCapacity'|'PercentChangeInCapacity',
Threshold=123.0,
ComparisonOperator='GreaterThanOrEqualToThreshold'|'GreaterThanThreshold'|'LessThanThreshold'|'LessThanOrEqualToThreshold',
EvaluationPeriods=123,
MetricName='ActivatingGameSessions'|'ActiveGameSessions'|'ActiveInstances'|'AvailablePlayerSessions'|'CurrentPlayerSessions'|'IdleInstances'
)
string
[REQUIRED]
Descriptive label associated with this scaling policy. Policy names do not need to be unique. A fleet can have only one scaling policy with the same name.
string
[REQUIRED]
Unique identity for the fleet to scale with this policy.
integer
[REQUIRED]
Amount of adjustment to make, based on the scaling adjustment type.
string
[REQUIRED]
Type of adjustment to make to a fleet's instance count (see FleetCapacity ):
ChangeInCapacity: add (or subtract) the scaling adjustment value from the current instance count. Positive values scale up while negative values scale down.
ExactCapacity: set the instance count to the scaling adjustment value.
PercentChangeInCapacity: increase or reduce the current instance count by the scaling adjustment, read as a percentage. Positive values scale up while negative values scale down; for example, a value of "-10" scales the fleet down by 10%.
float
[REQUIRED]
Metric value used to trigger a scaling event.
string
[REQUIRED]
Comparison operator to use when measuring the metric against the threshold value.
integer
[REQUIRED]
Length of time (in minutes) the metric must be at or beyond the threshold before a scaling event is triggered.
string
[REQUIRED]
Name of the Service-defined metric that is used to trigger an adjustment.
ActivatingGameSessions: number of game sessions in the process of being created (game session status = ACTIVATING).
ActiveGameSessions: number of game sessions currently running (game session status = ACTIVE).
CurrentPlayerSessions: number of active or reserved player sessions (player session status = ACTIVE or RESERVED).
AvailablePlayerSessions: number of player session slots currently available in active game sessions across the fleet, calculated by subtracting a game session's current player session count from its maximum player session count. This number includes game sessions that are not currently accepting players (game session PlayerSessionCreationPolicy = DENY_ALL).
ActiveInstances: number of instances currently running a game session.
IdleInstances: number of instances not currently running a game session.
dict
Response Syntax
{
'Name': 'string'
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
Name (string) --
Descriptive label associated with this scaling policy. Policy names do not need to be unique.
Retrieves all scaling policies applied to a fleet.
To get a fleet's scaling policies, specify the fleet ID. You can filter this request by policy status, such as to retrieve only active scaling policies. Use the pagination parameters to retrieve results as a set of sequential pages. If successful, set of ScalingPolicy objects is returned for the fleet.
Request Syntax
client.describe_scaling_policies(
FleetId='string',
StatusFilter='ACTIVE'|'UPDATE_REQUESTED'|'UPDATING'|'DELETE_REQUESTED'|'DELETING'|'DELETED'|'ERROR',
Limit=123,
NextToken='string'
)
string
[REQUIRED]
Unique identifier for a fleet. Specify the fleet to retrieve scaling policies for.
string
Game session status to filter results on. A scaling policy is only in force when in an Active state.
ACTIVE: The scaling policy is currently in force.
UPDATEREQUESTED: A request to update the scaling policy has been received.
UPDATING: A change is being made to the scaling policy.
DELETEREQUESTED: A request to delete the scaling policy has been received.
DELETING: The scaling policy is being deleted.
DELETED: The scaling policy has been deleted.
ERROR: An error occurred in creating the policy. It should be removed and recreated.
integer
Maximum number of results to return. You can use this parameter with NextToken to get results as a set of sequential pages.
string
Token indicating the start of the next sequential page of results. Use the token that is returned with a previous call to this action. To specify the start of the result set, do not specify a value.
dict
Response Syntax
{
'ScalingPolicies': [
{
'FleetId': 'string',
'Name': 'string',
'Status': 'ACTIVE'|'UPDATE_REQUESTED'|'UPDATING'|'DELETE_REQUESTED'|'DELETING'|'DELETED'|'ERROR',
'ScalingAdjustment': 123,
'ScalingAdjustmentType': 'ChangeInCapacity'|'ExactCapacity'|'PercentChangeInCapacity',
'ComparisonOperator': 'GreaterThanOrEqualToThreshold'|'GreaterThanThreshold'|'LessThanThreshold'|'LessThanOrEqualToThreshold',
'Threshold': 123.0,
'EvaluationPeriods': 123,
'MetricName': 'ActivatingGameSessions'|'ActiveGameSessions'|'ActiveInstances'|'AvailablePlayerSessions'|'CurrentPlayerSessions'|'IdleInstances'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
ScalingPolicies (list) --
Collection of objects containing the scaling policies matching the request.
(dict) --
Rule that controls how a fleet is scaled. Scaling policies are uniquely identified by the combination of name and fleet ID.
FleetId (string) --
Unique identity for the fleet associated with this scaling policy.
Name (string) --
Descriptive label associated with this scaling policy. Policy names do not need to be unique.
Status (string) --
Current status of the scaling policy. The scaling policy is only in force when in an Active state.
ACTIVE: The scaling policy is currently in force.
UPDATEREQUESTED: A request to update the scaling policy has been received.
UPDATING: A change is being made to the scaling policy.
DELETEREQUESTED: A request to delete the scaling policy has been received.
DELETING: The scaling policy is being deleted.
DELETED: The scaling policy has been deleted.
ERROR: An error occurred in creating the policy. It should be removed and recreated.
ScalingAdjustment (integer) --
Amount of adjustment to make, based on the scaling adjustment type.
ScalingAdjustmentType (string) --
Type of adjustment to make to a fleet's instance count (see FleetCapacity ):
ChangeInCapacity: add (or subtract) the scaling adjustment value from the current instance count. Positive values scale up while negative values scale down.
ExactCapacity: set the instance count to the scaling adjustment value.
PercentChangeInCapacity: increase or reduce the current instance count by the scaling adjustment, read as a percentage. Positive values scale up while negative values scale down.
ComparisonOperator (string) --
Comparison operator to use when measuring a metric against the threshold value.
Threshold (float) --
Metric value used to trigger a scaling event.
EvaluationPeriods (integer) --
Length of time (in minutes) the metric must be at or beyond the threshold before a scaling event is triggered.
MetricName (string) --
Name of the GameLift-defined metric that is used to trigger an adjustment.
ActivatingGameSessions: number of game sessions in the process of being created (game session status = ACTIVATING).
ActiveGameSessions: number of game sessions currently running (game session status = ACTIVE).
CurrentPlayerSessions: number of active or reserved player sessions (player session status = ACTIVE or RESERVED).
AvailablePlayerSessions: number of player session slots currently available in active game sessions across the fleet, calculated by subtracting a game session's current player session count from its maximum player session count. This number does include game sessions that are not currently accepting players (game session PlayerSessionCreationPolicy = DENY_ALL).
ActiveInstances: number of instances currently running a game session.
IdleInstances: number of instances not currently running a game session.
NextToken (string) --
Token indicating where to resume retrieving results on the next call to this action. If no token is returned, these results represent the end of the list.
Note
If a request has a limit that exactly matches the number of remaining results, a token is returned even though there are no more results to retrieve.
Retrieves properties, including the protection policy in force, for one or more game sessions. This action can be used in several ways: (1) provide a GameSessionId to request details for a specific game session; (2) provide either a FleetId or an AliasId to request properties for all game sessions running on a fleet.
To get game session record(s), specify just one of the following: game session ID, fleet ID, or alias ID. You can filter this request by game session status. Use the pagination parameters to retrieve results as a set of sequential pages. If successful, a GameSessionDetail object is returned for each session matching the request.
Request Syntax
client.describe_game_session_details(
FleetId='string',
GameSessionId='string',
AliasId='string',
StatusFilter='string',
Limit=123,
NextToken='string'
)
string
Unique identifier for a fleet. Specify a fleet to retrieve information on all game sessions active on the fleet.
string
Unique identifier for a game session. Specify the game session to retrieve information on.
string
Unique identifier for a fleet alias. Specify an alias to retrieve information on all game sessions active on the fleet.
string
Game session status to filter results on. Possible game session states include ACTIVE, TERMINATED, ACTIVATING and TERMINATING (the last two are transitory).
integer
Maximum number of results to return. You can use this parameter with NextToken to get results as a set of sequential pages.
string
Token indicating the start of the next sequential page of results. Use the token that is returned with a previous call to this action. To specify the start of the result set, do not specify a value.
dict
Response Syntax
{
'GameSessionDetails': [
{
'GameSession': {
'GameSessionId': 'string',
'Name': 'string',
'FleetId': 'string',
'CreationTime': datetime(2015, 1, 1),
'TerminationTime': datetime(2015, 1, 1),
'CurrentPlayerSessionCount': 123,
'MaximumPlayerSessionCount': 123,
'Status': 'ACTIVE'|'ACTIVATING'|'TERMINATED'|'TERMINATING',
'GameProperties': [
{
'Key': 'string',
'Value': 'string'
},
],
'IpAddress': 'string',
'PlayerSessionCreationPolicy': 'ACCEPT_ALL'|'DENY_ALL'
},
'ProtectionPolicy': 'NoProtection'|'FullProtection'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
GameSessionDetails (list) --
Collection of objects containing game session properties and the protection policy currently in force for each session matching the request.
(dict) --
A game session's properties and the protection policy currently in force.
GameSession (dict) --
Properties describing a game session.
GameSessionId (string) --
Unique identifier for a game session.
Name (string) --
Descriptive label associated with this game session. Session names do not need to be unique.
FleetId (string) --
Unique identifier for a fleet.
CreationTime (datetime) --
Time stamp indicating when this object was created. Format is an integer representing the number of seconds since the Unix epoch (Unix time).
TerminationTime (datetime) --
Time stamp indicating when this fleet was terminated. Format is an integer representing the number of seconds since the Unix epoch (Unix time).
CurrentPlayerSessionCount (integer) --
Number of players currently in the game session.
MaximumPlayerSessionCount (integer) --
Maximum number of players allowed in the game session.
Status (string) --
Current status of the game session. A game session must be in an ACTIVE state to have player sessions.
GameProperties (list) --
Set of custom properties for the game session.
(dict) --
Set of key-value pairs containing information your game server requires to set up sessions. This object allows you to pass in any set of data needed for your game. For more information, see the Amazon GameLift Developer Guide.
Key (string) --
Value (string) --
IpAddress (string) --
IP address of the game session.
PlayerSessionCreationPolicy (string) --
Indicates whether or not the game session is accepting new players.
ProtectionPolicy (string) --
Current status of protection for the game session.
NoProtection: The game session can be terminated during a scale-down event.
FullProtection: If the game session is in an ACTIVE status, it cannot be terminated during a scale-down event.
NextToken (string) --
Token indicating where to resume retrieving results on the next call to this action. If no token is returned, these results represent the end of the list.
Note
If a request has a limit that exactly matches the number of remaining results, a token is returned even though there are no more results to retrieve.
Deletes a fleet scaling policy. This action means that the policy is no longer in force and removes all record of it. To delete a scaling policy, specify both the scaling policy name and the fleet ID it is associated with.
Request Syntax
client.delete_scaling_policy(
Name='string',
FleetId='string'
)
string
[REQUIRED]
Descriptive label associated with this scaling policy. Policy names do not need to be unique.
string
[REQUIRED]
Unique identifier for a fleet.
None
{'StorageLocation': {'Bucket': 'string', 'Key': 'string', 'RoleArn': 'string'}}
Response {'StorageLocation': {'RoleArn': 'string'}}
Initializes a new build record and generates information required to upload a game build to Amazon GameLift. Once the build record has been created and is in an INITIALIZED state, you can upload your game build.
Warning
To create a build, use the CLI command upload-build , which creates a new build record and uploads the build files in one step. (See the Amazon GameLift Developer Guide for more details on the CLI and the upload process.) Call the CreateBuild action only if you have your own Amazon Simple Storage Service (Amazon S3) client and need to manually upload your build files.
To create a new build, optionally specify a build name and version. This metadata is stored with other properties in the build record and is displayed in the GameLift console (but not visible to players). If successful, this action returns the newly created build record along with an Amazon S3 storage location and AWS account credentials. Use the location and credentials to upload your game build.
Request Syntax
client.create_build(
Name='string',
Version='string',
StorageLocation={
'Bucket': 'string',
'Key': 'string',
'RoleArn': 'string'
}
)
string
Descriptive label associated with this build. Build names do not need to be unique. A build name can be changed later using UpdateBuild.
string
Version associated with this build. Version strings do not need to be unique to a build. A build version can be changed later using UpdateBuild.
dict
Location in Amazon Simple Storage Service (Amazon S3) where a build's files are stored. This location is assigned in response to a CreateBuild call, and is always in the same region as the service used to create the build. For more details see the Amazon S3 documentation.
Bucket (string) --
Amazon S3 bucket identifier.
Key (string) --
Amazon S3 bucket key.
RoleArn (string) --
dict
Response Syntax
{
'Build': {
'BuildId': 'string',
'Name': 'string',
'Version': 'string',
'Status': 'INITIALIZED'|'READY'|'FAILED',
'SizeOnDisk': 123,
'CreationTime': datetime(2015, 1, 1)
},
'UploadCredentials': {
'AccessKeyId': 'string',
'SecretAccessKey': 'string',
'SessionToken': 'string'
},
'StorageLocation': {
'Bucket': 'string',
'Key': 'string',
'RoleArn': 'string'
}
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
Build (dict) --
Set of properties for the newly created build.
BuildId (string) --
Unique identifier for a build.
Name (string) --
Descriptive label associated with this build. Build names do not need to be unique. It can be set using CreateBuild or UpdateBuild.
Version (string) --
Version associated with this build. Version strings do not need to be unique to a build. This value can be set using CreateBuild or UpdateBuild.
Status (string) --
Current status of the build. Possible build states include:
INITIALIZED: A new build has been defined, but no files have been uploaded. You cannot create fleets for builds that are in this state. When a build is successfully created, the build state is set to this value.
READY: The game build has been successfully uploaded. You can now create new fleets for this build.
FAILED: The game build upload failed. You cannot create new fleets for this build.
SizeOnDisk (integer) --
File size of the uploaded game build, expressed in bytes. When the build state is INITIALIZED, this value is 0.
CreationTime (datetime) --
Time stamp indicating when this object was created. Format is an integer representing the number of seconds since the Unix epoch (Unix time).
UploadCredentials (dict) --
AWS credentials required when uploading a game build to the storage location. These credentials have a limited lifespan and are valid only for the build they were issued for. If you need to get fresh credentials, call RequestUploadCredentials.
AccessKeyId (string) --
Access key for an AWS account.
SecretAccessKey (string) --
Secret key for an AWS account.
SessionToken (string) --
Token specific to a build ID.
StorageLocation (dict) --
Amazon S3 path and key, identifying where the game build files are stored.
Bucket (string) --
Amazon S3 bucket identifier.
Key (string) --
Amazon S3 bucket key.
RoleArn (string) --
{'NewGameSessionProtectionPolicy': 'NoProtection | FullProtection'}
Response {'FleetAttributes': {'NewGameSessionProtectionPolicy': 'NoProtection | '
'FullProtection'}}
Creates a new fleet to host game servers. A fleet consists of a set of Amazon Elastic Compute Cloud (Amazon EC2) instances of a certain type, which defines the CPU, memory, storage, and networking capacity of each host in the fleet. See Amazon EC2 Instance Types for more information. Each instance in the fleet hosts a game server created from the specified game build. Once a fleet is in an ACTIVE state, it can begin hosting game sessions.
To create a new fleet, provide a name and the EC2 instance type for the new fleet, and specify the build and server launch path. Builds must be in a READY state before they can be used to build fleets. When configuring the new fleet, you can optionally (1) provide a set of launch parameters to be passed to a game server when activated; (2) limit incoming traffic to a specified range of IP addresses and port numbers; (3) set game session protection for all instances in the fleet, and (4) configure Amazon GameLift to store game session logs by specifying the path to the logs stored in your game server files. If the call is successful, Amazon GameLift performs the following tasks:
Creates a fleet record and sets the state to NEW.
Sets the fleet's capacity to 1 "desired" and 1 "active" EC2 instance count.
Creates an EC2 instance and begins the process of initializing the fleet and activating a game server on the instance.
Begins writing events to the fleet event log, which can be accessed in the GameLift console.
Once a fleet is created, use the following actions to change certain fleet properties (server launch parameters and log paths cannot be changed):
UpdateFleetAttributes -- Update fleet metadata, including name and description.
UpdateFleetCapacity -- Increase or decrease the number of instances you want the fleet to maintain.
UpdateFleetPortSettings -- Change the IP addresses and ports that allow access to incoming traffic.
Request Syntax
client.create_fleet(
Name='string',
Description='string',
BuildId='string',
ServerLaunchPath='string',
ServerLaunchParameters='string',
LogPaths=[
'string',
],
EC2InstanceType='t2.micro'|'t2.small'|'t2.medium'|'t2.large'|'c3.large'|'c3.xlarge'|'c3.2xlarge'|'c3.4xlarge'|'c3.8xlarge'|'c4.large'|'c4.xlarge'|'c4.2xlarge'|'c4.4xlarge'|'c4.8xlarge'|'r3.large'|'r3.xlarge'|'r3.2xlarge'|'r3.4xlarge'|'r3.8xlarge'|'m3.medium'|'m3.large'|'m3.xlarge'|'m3.2xlarge'|'m4.large'|'m4.xlarge'|'m4.2xlarge'|'m4.4xlarge'|'m4.10xlarge',
EC2InboundPermissions=[
{
'FromPort': 123,
'ToPort': 123,
'IpRange': 'string',
'Protocol': 'TCP'|'UDP'
},
],
NewGameSessionProtectionPolicy='NoProtection'|'FullProtection'
)
string
[REQUIRED]
Descriptive label associated with this fleet. Fleet names do not need to be unique.
string
Human-readable description of the fleet.
string
[REQUIRED]
Unique identifier for the build you want the new fleet to use.
string
[REQUIRED]
Path to the launch executable for the game server. A game server is built into a C:\game drive. This value must be expressed as C:\game\[launchpath] . Example: If, when built, your game server files are in a folder called "MyGame", your log path should be C:\game\MyGame\server.exe .
string
Parameters required to launch your game server. These parameters should be expressed as a string of command-line parameters. Example: "+sv_port 33435 +start_lobby".
list
Path to game-session log files generated by your game server. Once a game session has been terminated, Amazon GameLift captures and stores the logs on Amazon S3. Use the GameLift console to access the stored logs.
(string) --
string
[REQUIRED]
Type of EC2 instances used in the fleet. EC2 instance types define the CPU, memory, storage, and networking capacity of the fleetaposs hosts. Amazon GameLift supports the EC2 instance types listed below. See Amazon EC2 Instance Types for detailed descriptions of each.
list
Access limits for incoming traffic. Setting these values limits game server access to incoming traffic using specified IP ranges and port numbers. Some ports in a range may be restricted. You can provide one or more sets of permissions for the fleet.
(dict) --
IP addresses and port settings used to limit access by incoming traffic (players) to a fleet. Permissions specify a range of IP addresses and port settings that must be used to gain access to a game server on a fleet machine.
FromPort (integer) -- [REQUIRED]
Starting value for a range of allowed port numbers.
ToPort (integer) -- [REQUIRED]
Ending value for a range of allowed port numbers. Port numbers are end-inclusive. This value must be higher than FromPort .
IpRange (string) -- [REQUIRED]
Range of allowed IP addresses. This value must be expressed in CIDR notation. Example: " 000.000.000.000/[subnet mask] " or optionally the shortened version " 0.0.0.0/[subnet mask] ".
Protocol (string) -- [REQUIRED]
Network communication protocol used by the fleet.
string
Game session protection policy to apply to all instances created in this fleet. If this parameter is not set, new instances in this fleet will default to no protection. Protection can be set for individual instances using UpdateGameSession.
NoProtection: The game session can be terminated during a scale-down event.
FullProtection: If the game session is in an ACTIVE status, it cannot be terminated during a scale-down event.
dict
Response Syntax
{
'FleetAttributes': {
'FleetId': 'string',
'Description': 'string',
'Name': 'string',
'CreationTime': datetime(2015, 1, 1),
'TerminationTime': datetime(2015, 1, 1),
'Status': 'NEW'|'DOWNLOADING'|'VALIDATING'|'BUILDING'|'ACTIVATING'|'ACTIVE'|'DELETING'|'ERROR'|'TERMINATED',
'BuildId': 'string',
'ServerLaunchPath': 'string',
'ServerLaunchParameters': 'string',
'LogPaths': [
'string',
],
'NewGameSessionProtectionPolicy': 'NoProtection'|'FullProtection'
}
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
FleetAttributes (dict) --
Properties for the newly created fleet.
FleetId (string) --
Unique identifier for a fleet.
Description (string) --
Human-readable description of the fleet.
Name (string) --
Descriptive label associated with this fleet. Fleet names do not need to be unique.
CreationTime (datetime) --
Time stamp indicating when this object was created. Format is an integer representing the number of seconds since the Unix epoch (Unix time).
TerminationTime (datetime) --
Time stamp indicating when this fleet was terminated. Format is an integer representing the number of seconds since the Unix epoch (Unix time).
Status (string) --
Current status of the fleet. Possible fleet states include:
NEW: A new fleet has been defined and hosts allocated.
DOWNLOADING/VALIDATING/BUILDING/ACTIVATING: The new fleet is being set up with the game build, and new hosts are being started.
ACTIVE: Hosts can now accept game sessions.
ERROR: An error occurred when downloading, validating, building, or activating the fleet.
DELETING: Hosts are responding to a delete fleet request.
TERMINATED: The fleet no longer exists.
BuildId (string) --
Unique identifier for a build.
ServerLaunchPath (string) --
Path to the launch executable for the game server. A game server is built into a C:\game drive. This value must be expressed as C:\game\[launchpath] . Example: If, when built, your game server files are in a folder called "MyGame", your log path should be C:\game\MyGame\server.exe .
ServerLaunchParameters (string) --
Parameters required to launch your game server. These parameters should be expressed as a string of command-line parameters. Example: "+sv_port 33435 +start_lobby".
LogPaths (list) --
Path to game-session log files generated by your game server. Once a game session has been terminated, Amazon GameLift captures and stores the logs on Amazon S3. Use the GameLift console to access the stored logs.
(string) --
NewGameSessionProtectionPolicy (string) --
Type of game session protection to set for all new instances started in the fleet.
NoProtection: The game session can be terminated during a scale-down event.
FullProtection: If the game session is in an ACTIVE status, it cannot be terminated during a scale-down event.
{'FleetAttributes': {'NewGameSessionProtectionPolicy': 'NoProtection | '
'FullProtection'}}
Retrieves fleet properties, including metadata, status, and configuration, for one or more fleets. You can request attributes for all fleets, or specify a list of one or more fleet IDs. When requesting all fleets, use the pagination parameters to retrieve results as a set of sequential pages. If successful, a FleetAttributes object is returned for each requested fleet ID. When specifying a list of fleet IDs, attribute objects are returned only for fleets that currently exist.
Note
Some API actions may limit the number of fleet IDs allowed in one request. If a request exceeds this limit, the request fails and the error message includes the maximum allowed.
Request Syntax
client.describe_fleet_attributes(
FleetIds=[
'string',
],
Limit=123,
NextToken='string'
)
list
Unique identifiers for the fleet(s) that you want to retrieve attributes for. Leave this parameter empty to retrieve attributes for all fleets.
(string) --
integer
Maximum number of results to return. You can use this parameter with NextToken to get results as a set of sequential pages. This parameter is ignored when the request specifies one or a list of fleet IDs.
string
Token indicating the start of the next sequential page of results. Use the token that is returned with a previous call to this action. To specify the start of the result set, do not specify a value. This parameter is ignored when the request specifies one or a list of fleet IDs.
dict
Response Syntax
{
'FleetAttributes': [
{
'FleetId': 'string',
'Description': 'string',
'Name': 'string',
'CreationTime': datetime(2015, 1, 1),
'TerminationTime': datetime(2015, 1, 1),
'Status': 'NEW'|'DOWNLOADING'|'VALIDATING'|'BUILDING'|'ACTIVATING'|'ACTIVE'|'DELETING'|'ERROR'|'TERMINATED',
'BuildId': 'string',
'ServerLaunchPath': 'string',
'ServerLaunchParameters': 'string',
'LogPaths': [
'string',
],
'NewGameSessionProtectionPolicy': 'NoProtection'|'FullProtection'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
FleetAttributes (list) --
Collection of objects containing attribute metadata for each requested fleet ID.
(dict) --
General properties describing a fleet.
FleetId (string) --
Unique identifier for a fleet.
Description (string) --
Human-readable description of the fleet.
Name (string) --
Descriptive label associated with this fleet. Fleet names do not need to be unique.
CreationTime (datetime) --
Time stamp indicating when this object was created. Format is an integer representing the number of seconds since the Unix epoch (Unix time).
TerminationTime (datetime) --
Time stamp indicating when this fleet was terminated. Format is an integer representing the number of seconds since the Unix epoch (Unix time).
Status (string) --
Current status of the fleet. Possible fleet states include:
NEW: A new fleet has been defined and hosts allocated.
DOWNLOADING/VALIDATING/BUILDING/ACTIVATING: The new fleet is being set up with the game build, and new hosts are being started.
ACTIVE: Hosts can now accept game sessions.
ERROR: An error occurred when downloading, validating, building, or activating the fleet.
DELETING: Hosts are responding to a delete fleet request.
TERMINATED: The fleet no longer exists.
BuildId (string) --
Unique identifier for a build.
ServerLaunchPath (string) --
Path to the launch executable for the game server. A game server is built into a C:\game drive. This value must be expressed as C:\game\[launchpath] . Example: If, when built, your game server files are in a folder called "MyGame", your log path should be C:\game\MyGame\server.exe .
ServerLaunchParameters (string) --
Parameters required to launch your game server. These parameters should be expressed as a string of command-line parameters. Example: "+sv_port 33435 +start_lobby".
LogPaths (list) --
Path to game-session log files generated by your game server. Once a game session has been terminated, Amazon GameLift captures and stores the logs on Amazon S3. Use the GameLift console to access the stored logs.
(string) --
NewGameSessionProtectionPolicy (string) --
Type of game session protection to set for all new instances started in the fleet.
NoProtection: The game session can be terminated during a scale-down event.
FullProtection: If the game session is in an ACTIVE status, it cannot be terminated during a scale-down event.
NextToken (string) --
Token indicating where to resume retrieving results on the next call to this action. If no token is returned, these results represent the end of the list.
Note
If a request has a limit that exactly matches the number of remaining results, a token is returned even though there are no more results to retrieve.
{'FleetCapacity': {'InstanceCounts': {'IDLE': 'integer',
'MAXIMUM': 'integer',
'MINIMUM': 'integer'}}}
Retrieves the current status of fleet capacity for one or more fleets. This information includes the number of instances that have been requested for the fleet and the number currently active. You can request capacity for all fleets, or specify a list of one or more fleet IDs. When requesting all fleets, use the pagination parameters to retrieve results as a set of sequential pages. If successful, a FleetCapacity object is returned for each requested fleet ID. When specifying a list of fleet IDs, attribute objects are returned only for fleets that currently exist.
Note
Some API actions may limit the number of fleet IDs allowed in one request. If a request exceeds this limit, the request fails and the error message includes the maximum allowed.
Request Syntax
client.describe_fleet_capacity(
FleetIds=[
'string',
],
Limit=123,
NextToken='string'
)
list
Unique identifier for the fleet(s) you want to retrieve capacity information for.
(string) --
integer
Maximum number of results to return. You can use this parameter with NextToken to get results as a set of sequential pages. This parameter is ignored when the request specifies one or a list of fleet IDs.
string
Token indicating the start of the next sequential page of results. Use the token that is returned with a previous call to this action. To specify the start of the result set, do not specify a value. This parameter is ignored when the request specifies one or a list of fleet IDs.
dict
Response Syntax
{
'FleetCapacity': [
{
'FleetId': 'string',
'InstanceType': 't2.micro'|'t2.small'|'t2.medium'|'t2.large'|'c3.large'|'c3.xlarge'|'c3.2xlarge'|'c3.4xlarge'|'c3.8xlarge'|'c4.large'|'c4.xlarge'|'c4.2xlarge'|'c4.4xlarge'|'c4.8xlarge'|'r3.large'|'r3.xlarge'|'r3.2xlarge'|'r3.4xlarge'|'r3.8xlarge'|'m3.medium'|'m3.large'|'m3.xlarge'|'m3.2xlarge'|'m4.large'|'m4.xlarge'|'m4.2xlarge'|'m4.4xlarge'|'m4.10xlarge',
'InstanceCounts': {
'DESIRED': 123,
'MINIMUM': 123,
'MAXIMUM': 123,
'PENDING': 123,
'ACTIVE': 123,
'IDLE': 123,
'TERMINATING': 123
}
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
FleetCapacity (list) --
Collection of objects containing capacity information for each requested fleet ID. Leave this parameter empty to retrieve capacity information for all fleets.
(dict) --
Information about the fleet's capacity. Fleet capacity is measured in EC2 instances. By default, new fleets have a capacity of one instance, but can be updated as needed. The maximum number of instances for a fleet is determined by the fleet's instance type.
FleetId (string) --
Unique identifier for a fleet.
InstanceType (string) --
Type of EC2 instances used in the fleet. EC2 instance types define the CPU, memory, storage, and networking capacity of the fleetaposs hosts. Amazon GameLift supports the EC2 instance types listed below. See Amazon EC2 Instance Types for detailed descriptions of each.
InstanceCounts (dict) --
Current status of fleet capacity.
DESIRED (integer) --
Ideal number of active instances in the fleet.
MINIMUM (integer) --
Minimum value allowed for the fleet's instance count.
MAXIMUM (integer) --
Maximum value allowed for the fleet's instance count.
PENDING (integer) --
Number of instances in the fleet that are starting but not yet active.
ACTIVE (integer) --
Actual number of active instances in the fleet.
IDLE (integer) --
Number of active instances in the fleet that are not currently hosting a game session.
TERMINATING (integer) --
Number of instances in the fleet that are no longer active but haven't yet been terminated.
NextToken (string) --
Token indicating where to resume retrieving results on the next call to this action. If no token is returned, these results represent the end of the list.
Note
If a request has a limit that exactly matches the number of remaining results, a token is returned even though there are no more results to retrieve.
{'Events': {'EventCode': {'FLEET_NEW_GAME_SESSION_PROTECTION_POLICY_UPDATED'}}}
Retrieves entries from the fleet event log. You can specify a time range to limit the result set. Use the pagination parameters to retrieve results as a set of sequential pages. If successful, a collection of event log entries matching the request are returned.
Request Syntax
client.describe_fleet_events(
FleetId='string',
StartTime=datetime(2015, 1, 1),
EndTime=datetime(2015, 1, 1),
Limit=123,
NextToken='string'
)
string
[REQUIRED]
Unique identifier for the fleet to get event logs for.
datetime
Earliest date to retrieve event logs for. If no start time is specified, this call returns entries starting from when the fleet was created to the specified end time. Format is an integer representing the number of seconds since the Unix epoch (Unix time).
datetime
Most recent date to retrieve event logs for. If no end time is specified, this call returns entries from the specified start time up to the present. Format is an integer representing the number of seconds since the Unix epoch (Unix time).
integer
Maximum number of results to return. You can use this parameter with NextToken to get results as a set of sequential pages.
string
Token indicating the start of the next sequential page of results. Use the token that is returned with a previous call to this action. To specify the start of the result set, do not specify a value.
dict
Response Syntax
{
'Events': [
{
'EventId': 'string',
'ResourceId': 'string',
'EventCode': 'GENERIC_EVENT'|'FLEET_CREATED'|'FLEET_DELETED'|'FLEET_SCALING_EVENT'|'FLEET_STATE_DOWNLOADING'|'FLEET_STATE_VALIDATING'|'FLEET_STATE_BUILDING'|'FLEET_STATE_ACTIVATING'|'FLEET_STATE_ACTIVE'|'FLEET_STATE_ERROR'|'FLEET_INITIALIZATION_FAILED'|'FLEET_BINARY_DOWNLOAD_FAILED'|'FLEET_VALIDATION_LAUNCH_PATH_NOT_FOUND'|'FLEET_VALIDATION_EXECUTABLE_RUNTIME_FAILURE'|'FLEET_VALIDATION_TIMED_OUT'|'FLEET_ACTIVATION_FAILED'|'FLEET_ACTIVATION_FAILED_NO_INSTANCES'|'FLEET_NEW_GAME_SESSION_PROTECTION_POLICY_UPDATED',
'Message': 'string',
'EventTime': datetime(2015, 1, 1)
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
Events (list) --
Collection of objects containing event log entries for the specified fleet.
(dict) --
Log entry describing an event involving an Amazon GameLift resource (such as a fleet).
EventId (string) --
Unique identifier for a fleet event.
ResourceId (string) --
Unique identifier for the resource, such as a fleet ID.
EventCode (string) --
Type of event being logged.
Message (string) --
Additional information related to the event.
EventTime (datetime) --
Time stamp indicating when this event occurred. Format is an integer representing the number of seconds since the Unix epoch (Unix time).
NextToken (string) --
Token indicating where to resume retrieving results on the next call to this action. If no token is returned, these results represent the end of the list.
Note
If a request has a limit that exactly matches the number of remaining results, a token is returned even though there are no more results to retrieve.
{'StorageLocation': {'RoleArn': 'string'}}
Retrieves a fresh set of upload credentials and the assigned Amazon S3 storage location for a specific build. Valid credentials are required to upload your game build files to Amazon S3.
Warning
Call this action only if you need credentials for a build created with CreateBuild. This is a rare situation; in most cases, builds are created using the CLI command upload-build , which creates a build record and also uploads build files.
Upload credentials are returned when you create the build, but they have a limited lifespan. You can get fresh credentials and use them to re-upload game files until the state of that build changes to READY. Once this happens, you must create a brand new build.
Request Syntax
client.request_upload_credentials(
BuildId='string'
)
string
[REQUIRED]
Unique identifier for the build you want to get credentials for.
dict
Response Syntax
{
'UploadCredentials': {
'AccessKeyId': 'string',
'SecretAccessKey': 'string',
'SessionToken': 'string'
},
'StorageLocation': {
'Bucket': 'string',
'Key': 'string',
'RoleArn': 'string'
}
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
UploadCredentials (dict) --
AWS credentials required when uploading a game build to the storage location. These credentials have a limited lifespan and are valid only for the build they were issued for.
AccessKeyId (string) --
Access key for an AWS account.
SecretAccessKey (string) --
Secret key for an AWS account.
SessionToken (string) --
Token specific to a build ID.
StorageLocation (dict) --
Amazon S3 path and key, identifying where the game build files are stored.
Bucket (string) --
Amazon S3 bucket identifier.
Key (string) --
Amazon S3 bucket key.
RoleArn (string) --
{'NewGameSessionProtectionPolicy': 'NoProtection | FullProtection'}
Updates fleet properties, including name and description, for a fleet. To update metadata, specify the fleet ID and the property values you want to change. If successful, the fleet ID for the updated fleet is returned.
Request Syntax
client.update_fleet_attributes(
FleetId='string',
Name='string',
Description='string',
NewGameSessionProtectionPolicy='NoProtection'|'FullProtection'
)
string
[REQUIRED]
Unique identifier for the fleet you want to update attribute metadata for.
string
Descriptive label associated with this fleet. Fleet names do not need to be unique.
string
Human-readable description of the fleet.
string
Game session protection policy to apply to all new instances created in this fleet. Instances that already exist will not be affected. You can set protection for individual instances using UpdateGameSession.
NoProtection: The game session can be terminated during a scale-down event.
FullProtection: If the game session is in an ACTIVE status, it cannot be terminated during a scale-down event.
dict
Response Syntax
{
'FleetId': 'string'
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
FleetId (string) --
Unique identifier for the updated fleet.
{'MaxSize': 'integer', 'MinSize': 'integer'}
Updates capacity settings for a fleet. Use this action to specify the number of EC2 instances (hosts) you want this fleet to contain. Before calling this action, you may want to call DescribeEC2InstanceLimits to get the maximum capacity based on the fleet's EC2 instance type.
If you're using auto-scaling (see PutScalingPolicy ), you may want to specify a minimum and/or maximum capacity. If you don't provide these boundaries, auto-scaling can set capacity anywhere between zero and the service limits.
To update fleet capacity, specify the fleet ID and the desired number of instances. If successful, Amazon GameLift starts or terminates instances so that the fleet's active instance count matches the desired instance count. You can view a fleet's current capacity information by calling DescribeFleetCapacity. If the desired instance count is higher than the instance type's limit, the "Limit Exceeded" exception will occur.
Request Syntax
client.update_fleet_capacity(
FleetId='string',
DesiredInstances=123,
MinSize=123,
MaxSize=123
)
string
[REQUIRED]
Unique identifier for the fleet you want to update capacity for.
integer
Number of EC2 instances you want this fleet to host.
integer
Minimum value allowed for the fleet's instance count. Default if not set is 0.
integer
Maximum value allowed for the fleet's instance count. Default if not set is 1.
dict
Response Syntax
{
'FleetId': 'string'
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
FleetId (string) --
Unique identifier for the updated fleet.
{'ProtectionPolicy': 'NoProtection | FullProtection'}
Updates game session properties. This includes the session name, maximum player count, protection policy, which controls whether or not an active game session can be terminated during a scale-down event, and the player session creation policy, which controls whether or not new players can join the session. To update a game session, specify the game session ID and the values you want to change. If successful, an updated GameSession object is returned.
Request Syntax
client.update_game_session(
GameSessionId='string',
MaximumPlayerSessionCount=123,
Name='string',
PlayerSessionCreationPolicy='ACCEPT_ALL'|'DENY_ALL',
ProtectionPolicy='NoProtection'|'FullProtection'
)
string
[REQUIRED]
Unique identifier for a game session. Specify the game session you want to update.
integer
Maximum number of players that can be simultaneously connected to the game session.
string
Descriptive label associated with this game session. Session names do not need to be unique.
string
Policy determining whether or not the game session accepts new players.
string
Game session protection policy to apply to this game session only.
NoProtection: The game session can be terminated during a scale-down event.
FullProtection: If the game session is in an ACTIVE status, it cannot be terminated during a scale-down event.
dict
Response Syntax
{
'GameSession': {
'GameSessionId': 'string',
'Name': 'string',
'FleetId': 'string',
'CreationTime': datetime(2015, 1, 1),
'TerminationTime': datetime(2015, 1, 1),
'CurrentPlayerSessionCount': 123,
'MaximumPlayerSessionCount': 123,
'Status': 'ACTIVE'|'ACTIVATING'|'TERMINATED'|'TERMINATING',
'GameProperties': [
{
'Key': 'string',
'Value': 'string'
},
],
'IpAddress': 'string',
'PlayerSessionCreationPolicy': 'ACCEPT_ALL'|'DENY_ALL'
}
}
Response Structure
(dict) --
Represents the returned data in response to a request action.
GameSession (dict) --
Object containing the updated game session metadata.
GameSessionId (string) --
Unique identifier for a game session.
Name (string) --
Descriptive label associated with this game session. Session names do not need to be unique.
FleetId (string) --
Unique identifier for a fleet.
CreationTime (datetime) --
Time stamp indicating when this object was created. Format is an integer representing the number of seconds since the Unix epoch (Unix time).
TerminationTime (datetime) --
Time stamp indicating when this fleet was terminated. Format is an integer representing the number of seconds since the Unix epoch (Unix time).
CurrentPlayerSessionCount (integer) --
Number of players currently in the game session.
MaximumPlayerSessionCount (integer) --
Maximum number of players allowed in the game session.
Status (string) --
Current status of the game session. A game session must be in an ACTIVE state to have player sessions.
GameProperties (list) --
Set of custom properties for the game session.
(dict) --
Set of key-value pairs containing information your game server requires to set up sessions. This object allows you to pass in any set of data needed for your game. For more information, see the Amazon GameLift Developer Guide.
Key (string) --
Value (string) --
IpAddress (string) --
IP address of the game session.
PlayerSessionCreationPolicy (string) --
Indicates whether or not the game session is accepting new players.