Amazon GameLift

2016/06/28 - Amazon GameLift - 2 new 9 updated api methods

UpdateRuntimeConfiguration (new) Link ¶

Updates the current runtime configuration for the specified fleet, which tells GameLift how to launch server processes on instances in the fleet. You can update a fleet's runtime configuration at any time after the fleet is created; it does not need to be in an ACTIVE state.

To update runtime configuration, specify the fleet ID and provide a RuntimeConfiguration object with the updated collection of server process configurations.

Each instance in a GameLift fleet checks regularly for an updated runtime configuration and changes how it launches server processes to comply with the latest version. Existing server processes are not affected by the update; they continue to run until they end, while GameLift simply adds new server processes to fit the current runtime configuration. As a result, the runtime configuration changes are applied gradually as existing processes shut down and new processes are launched in GameLift's normal process recycling activity.

Request Syntax

client.update_runtime_configuration(
    FleetId='string',
    RuntimeConfiguration={
        'ServerProcesses': [
            {
                'LaunchPath': 'string',
                'Parameters': 'string',
                'ConcurrentExecutions': 123
            },
        ]
    }
)
type FleetId

string

param FleetId

[REQUIRED]

Unique identifier of the fleet to update runtime configuration for.

type RuntimeConfiguration

dict

param RuntimeConfiguration

[REQUIRED]

Instructions for launching server processes on each instance in the fleet. The runtime configuration for a fleet has a collection of server process configurations, one for each type of server process to run on an instance. A server process configuration specifies the location of the server executable, launch parameters, and the number of concurrent processes with that configuration to maintain on each instance.

  • ServerProcesses (list) --

    Collection of server process configurations describing what server processes to run on each instance in a fleet

    • (dict) --

      A set of instructions for launching server processes on each instance in a fleet. Each instruction set identifies the location of the server executable, optional launch parameters, and the number of server processes with this configuration to maintain concurrently on the instance. Server process configurations make up a fleet's `` RuntimeConfiguration`` .

      • LaunchPath (string) -- [REQUIRED]

        Location in the game build of the server executable. All game builds are installed on instances at the root C:\game\... , so an executable file located at MyGame\latest\server.exe has a launch path of "C:\game\MyGame\latest\server.exe ".

      • Parameters (string) --

        Optional list of parameters to pass to the server executable on launch.

      • ConcurrentExecutions (integer) -- [REQUIRED]

        Number of server processes using this configuration to run concurrently on an instance.

rtype

dict

returns

Response Syntax

{
    'RuntimeConfiguration': {
        'ServerProcesses': [
            {
                'LaunchPath': 'string',
                'Parameters': 'string',
                'ConcurrentExecutions': 123
            },
        ]
    }
}

Response Structure

  • (dict) --

    Represents the returned data in response to a request action.

    • RuntimeConfiguration (dict) --

      The runtime configuration currently in force. If the update was successful, this object matches the one in the request.

      • ServerProcesses (list) --

        Collection of server process configurations describing what server processes to run on each instance in a fleet

        • (dict) --

          A set of instructions for launching server processes on each instance in a fleet. Each instruction set identifies the location of the server executable, optional launch parameters, and the number of server processes with this configuration to maintain concurrently on the instance. Server process configurations make up a fleet's `` RuntimeConfiguration`` .

          • LaunchPath (string) --

            Location in the game build of the server executable. All game builds are installed on instances at the root C:\game\... , so an executable file located at MyGame\latest\server.exe has a launch path of "C:\game\MyGame\latest\server.exe ".

          • Parameters (string) --

            Optional list of parameters to pass to the server executable on launch.

          • ConcurrentExecutions (integer) --

            Number of server processes using this configuration to run concurrently on an instance.

DescribeRuntimeConfiguration (new) Link ¶

Retrieves the current runtime configuration for the specified fleet. The runtime configuration tells GameLift how to launch server processes on instances in the fleet.

Request Syntax

client.describe_runtime_configuration(
    FleetId='string'
)
type FleetId

string

param FleetId

[REQUIRED]

Unique identifier of the fleet to get the runtime configuration for.

rtype

dict

returns

Response Syntax

{
    'RuntimeConfiguration': {
        'ServerProcesses': [
            {
                'LaunchPath': 'string',
                'Parameters': 'string',
                'ConcurrentExecutions': 123
            },
        ]
    }
}

Response Structure

  • (dict) --

    Represents the returned data in response to a request action.

    • RuntimeConfiguration (dict) --

      Instructions describing how server processes should be launched and maintained on each instance in the fleet.

      • ServerProcesses (list) --

        Collection of server process configurations describing what server processes to run on each instance in a fleet

        • (dict) --

          A set of instructions for launching server processes on each instance in a fleet. Each instruction set identifies the location of the server executable, optional launch parameters, and the number of server processes with this configuration to maintain concurrently on the instance. Server process configurations make up a fleet's `` RuntimeConfiguration`` .

          • LaunchPath (string) --

            Location in the game build of the server executable. All game builds are installed on instances at the root C:\game\... , so an executable file located at MyGame\latest\server.exe has a launch path of "C:\game\MyGame\latest\server.exe ".

          • Parameters (string) --

            Optional list of parameters to pass to the server executable on launch.

          • ConcurrentExecutions (integer) --

            Number of server processes using this configuration to run concurrently on an instance.

CreateFleet (updated) Link ¶
Changes (request)
{'RuntimeConfiguration': {'ServerProcesses': [{'ConcurrentExecutions': 'integer',
                                               'LaunchPath': 'string',
                                               'Parameters': 'string'}]}}

Creates a new fleet to run your game servers. A fleet is a set of Amazon Elastic Compute Cloud (Amazon EC2) instances, each of which can run multiple server processes to host game sessions. You configure a fleet to create instances with certain hardware specifications (see Amazon EC2 Instance Types for more information), and deploy a specified game build to each instance. A newly created fleet passes through several states; once it reaches the ACTIVE state, it can begin hosting game sessions.

To create a new fleet, provide a fleet name, an EC2 instance type, and a build ID of the game build to deploy. You can also configure the new fleet with the following settings: (1) a runtime configuration describing what server processes to run on each instance in the fleet (required to create fleet), (2) access permissions for inbound traffic, (3) fleet-wide game session protection, and (4) the location of default log files for GameLift to upload and store.

If the CreateFleet call is successful, Amazon GameLift performs the following tasks:

  • Creates a fleet record and sets the state to NEW (followed by other states as the fleet is activated).

  • Sets the fleet's capacity to 1 "desired", which causes GameLift to start one new EC2 instance.

  • Starts launching server processes on the instance. If the fleet is configured to run multiple server processes per instance, GameLift staggers each launch by a few seconds.

  • Begins writing events to the fleet event log, which can be accessed in the GameLift console.

  • Sets the fleet's status to ACTIVE once one server process in the fleet is ready to host a game session.

After a fleet is created, use the following actions to change fleet properties and configuration:

  • 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 address and port ranges that allow access to incoming traffic.

  • UpdateRuntimeConfiguration -- Change how server processes are launched in the fleet, including launch path, launch parameters, and the number of concurrent processes.

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',
    RuntimeConfiguration={
        'ServerProcesses': [
            {
                'LaunchPath': 'string',
                'Parameters': 'string',
                'ConcurrentExecutions': 123
            },
        ]
    }
)
type Name

string

param Name

[REQUIRED]

Descriptive label associated with a fleet. Fleet names do not need to be unique.

type Description

string

param Description

Human-readable description of a fleet.

type BuildId

string

param BuildId

[REQUIRED]

Unique identifier of the build to be deployed on the new fleet. The build must have been successfully uploaded to GameLift and be in a READY state. This fleet setting cannot be changed once the fleet is created.

type ServerLaunchPath

string

param ServerLaunchPath

This parameter is no longer used. Instead, specify a server launch path using the RuntimeConfiguration parameter. (Requests that specify a server launch path and launch parameters instead of a runtime configuration will continue to work.)

type ServerLaunchParameters

string

param ServerLaunchParameters

This parameter is no longer used. Instead, specify server launch parameters in the RuntimeConfiguration parameter. (Requests that specify a server launch path and launch parameters instead of a runtime configuration will continue to work.)

type LogPaths

list

param LogPaths

Location of default log files. When a server process is shut down, Amazon GameLift captures and stores any log files in this location. These logs are in addition to game session logs; see more on game session logs in the Amazon GameLift Developer Guide . If no default log path for a fleet is specified, GameLift will automatically upload logs stored on each instance at C:\game\logs . Use the GameLift console to access stored logs.

  • (string) --

type EC2InstanceType

string

param EC2InstanceType

[REQUIRED]

Name of an EC2 instance type that is supported in Amazon GameLift. A fleet instance type determines the computing resources of each instance in the fleet, including CPU, memory, storage, and networking capacity. GameLift supports the following EC2 instance types. See Amazon EC2 Instance Types for detailed descriptions.

type EC2InboundPermissions

list

param EC2InboundPermissions

Range of IP addresses and port settings that permit inbound traffic to access server processes running on the fleet. If no inbound permissions are set, including both IP address range and port range, the server processes in the fleet cannot accept connections. You can specify one or more sets of permissions for a fleet.

  • (dict) --

    A range of IP addresses and port settings that allow inbound traffic to connect to server processes on GameLift. Each game session hosted on a fleet is assigned a unique combination of IP address and port number, which must fall into the fleet's allowed ranges. This combination is included in the GameSession object.

    • 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.

type NewGameSessionProtectionPolicy

string

param NewGameSessionProtectionPolicy

Game session protection policy to apply to all instances in this fleet. If this parameter is not set, instances in this fleet default to no protection. You can change a fleet's protection policy using UpdateFleetAttributes, but this change will only affect sessions created after the policy change. You can also 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.

type RuntimeConfiguration

dict

param RuntimeConfiguration

Instructions for launching server processes on each instance in the fleet. The runtime configuration for a fleet has a collection of server process configurations, one for each type of server process to run on an instance. A server process configuration specifies the location of the server executable, launch parameters, and the number of concurrent processes with that configuration to maintain on each instance. A CreateFleet request must include a runtime configuration with at least one server process configuration; otherwise the request will fail with an invalid request exception. (This parameter replaces the parameters ServerLaunchPath and ServerLaunchParameters ; requests that contain values for these parameters instead of a runtime configuration will continue to work.)

  • ServerProcesses (list) --

    Collection of server process configurations describing what server processes to run on each instance in a fleet

    • (dict) --

      A set of instructions for launching server processes on each instance in a fleet. Each instruction set identifies the location of the server executable, optional launch parameters, and the number of server processes with this configuration to maintain concurrently on the instance. Server process configurations make up a fleet's `` RuntimeConfiguration`` .

      • LaunchPath (string) -- [REQUIRED]

        Location in the game build of the server executable. All game builds are installed on instances at the root C:\game\... , so an executable file located at MyGame\latest\server.exe has a launch path of "C:\game\MyGame\latest\server.exe ".

      • Parameters (string) --

        Optional list of parameters to pass to the server executable on launch.

      • ConcurrentExecutions (integer) -- [REQUIRED]

        Number of server processes using this configuration to run concurrently on an instance.

rtype

dict

returns

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 a 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 the following:

        • NEW – A new fleet has been defined and desired instances is set to 1.

        • DOWNLOADING/VALIDATING/BUILDING/ACTIVATING – GameLift is setting up the new fleet, creating new instances with the game build and starting server processes.

        • 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) --

        Deprecated. Server launch parameters are now set using a `` RuntimeConfiguration`` object.

      • ServerLaunchParameters (string) --

        Deprecated. Server launch parameters are now specified using a `` RuntimeConfiguration`` object.

      • LogPaths (list) --

        Location of default log files. When a server process is shut down, Amazon GameLift captures and stores any log files in this location. These logs are in addition to game session logs; see more on game session logs in the Amazon GameLift Developer Guide . If no default log path for a fleet is specified, GameLift will automatically upload logs stored on each instance at C:\game\logs . Use the GameLift console to access 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.

CreateGameSession (updated) Link ¶
Changes (response)
{'GameSession': {'Port': 'integer'}}

Creates a multiplayer game session for players. This action creates a game session record and assigns the new session to an instance in the specified fleet, which initializes a new server process to host the game session. A fleet must be in an ACTIVE state before a game session can be created in it.

To create a game session, specify either a fleet ID or an alias ID and indicate the maximum number of players the game session allows. You can also provide a name and a set of properties for your game (optional). If successful, a GameSession object is returned containing session properties, including an IP address. By default, newly created game sessions are set to accept adding any new players to the game session. Use UpdateGameSession to change the creation policy.

Request Syntax

client.create_game_session(
    FleetId='string',
    AliasId='string',
    MaximumPlayerSessionCount=123,
    Name='string',
    GameProperties=[
        {
            'Key': 'string',
            'Value': 'string'
        },
    ]
)
type FleetId

string

param FleetId

Unique identifier for a fleet. Each request must reference either a fleet ID or alias ID, but not both.

type AliasId

string

param AliasId

Unique identifier for a fleet alias. Each request must reference either a fleet ID or alias ID, but not both.

type MaximumPlayerSessionCount

integer

param MaximumPlayerSessionCount

[REQUIRED]

Maximum number of players that can be connected simultaneously to the game session.

type Name

string

param Name

Descriptive label associated with a game session. Session names do not need to be unique.

type GameProperties

list

param GameProperties

Set of properties used to administer a game session. These properties are passed to the server process hosting it.

  • (dict) --

    Set of key-value pairs containing information a server process requires to set up a game session. 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) -- [REQUIRED]

    • Value (string) -- [REQUIRED]

rtype

dict

returns

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',
        'Port': 123,
        'PlayerSessionCreationPolicy': 'ACCEPT_ALL'|'DENY_ALL'
    }
}

Response Structure

  • (dict) --

    Represents the returned data in response to a request action.

    • GameSession (dict) --

      Object containing the newly created game session record.

      • GameSessionId (string) --

        Unique identifier for a game session.

      • Name (string) --

        Descriptive label associated with a 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 a server process requires to set up a game session. 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. To connect to a GameLift server process, an app needs both the IP address and port number.

      • Port (integer) --

        Port number for the game session. To connect to a GameLift server process, an app needs both the IP address and port number.

      • PlayerSessionCreationPolicy (string) --

        Indicates whether or not the game session is accepting new players.

CreatePlayerSession (updated) Link ¶
Changes (response)
{'PlayerSession': {'Port': 'integer'}}

Adds a player to a game session and creates a player session record. A game session must be in an ACTIVE state, have a creation policy of ALLOW_ALL , and have an open player slot before players can be added to the session.

To create a player session, specify a game session ID and player ID. If successful, the player is added to the game session and a new PlayerSession object is returned.

Request Syntax

client.create_player_session(
    GameSessionId='string',
    PlayerId='string'
)
type GameSessionId

string

param GameSessionId

[REQUIRED]

Unique identifier for a game session. Specify the game session you want to add a player to.

type PlayerId

string

param PlayerId

[REQUIRED]

Unique identifier for the player to be added.

rtype

dict

returns

Response Syntax

{
    'PlayerSession': {
        'PlayerSessionId': 'string',
        'PlayerId': 'string',
        'GameSessionId': 'string',
        'FleetId': 'string',
        'CreationTime': datetime(2015, 1, 1),
        'TerminationTime': datetime(2015, 1, 1),
        'Status': 'RESERVED'|'ACTIVE'|'COMPLETED'|'TIMEDOUT',
        'IpAddress': 'string',
        'Port': 123
    }
}

Response Structure

  • (dict) --

    Represents the returned data in response to a request action.

    • PlayerSession (dict) --

      Object containing the newly created player session record.

      • PlayerSessionId (string) --

        Unique identifier for a player session.

      • PlayerId (string) --

        Unique identifier for a player.

      • GameSessionId (string) --

        Unique identifier for a game session.

      • 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).

      • Status (string) --

        Current status of the player session. Possible player session states include the following:

        • RESERVED – The player session request has been received, but the player has not yet connected to the server process and/or been validated.

        • ACTIVE – The player has been validated by the server process and is currently connected.

        • COMPLETED – The player connection has been dropped.

        • TIMEDOUT – A player session request was received, but the player did not connect and/or was not validated within the time-out limit (60 seconds).

      • IpAddress (string) --

        Game session IP address. All player sessions reference the game session location.

      • Port (integer) --

        Port number for the game session. To connect to a GameLift server process, an app needs both the IP address and port number.

CreatePlayerSessions (updated) Link ¶
Changes (response)
{'PlayerSessions': {'Port': 'integer'}}

Adds a group of players to a game session. Similar to CreatePlayerSession , this action allows you to add multiple players in a single call, which is useful for games that provide party and/or matchmaking features. A game session must be in an ACTIVE state, have a creation policy of ALLOW_ALL , and have an open player slot before players can be added to the session.

To create player sessions, specify a game session ID and a list of player IDs. If successful, the players are added to the game session and a set of new PlayerSession objects is returned.

Request Syntax

client.create_player_sessions(
    GameSessionId='string',
    PlayerIds=[
        'string',
    ]
)
type GameSessionId

string

param GameSessionId

[REQUIRED]

Unique identifier for a game session.

type PlayerIds

list

param PlayerIds

[REQUIRED]

List of unique identifiers for the players to be added.

  • (string) --

rtype

dict

returns

Response Syntax

{
    'PlayerSessions': [
        {
            'PlayerSessionId': 'string',
            'PlayerId': 'string',
            'GameSessionId': 'string',
            'FleetId': 'string',
            'CreationTime': datetime(2015, 1, 1),
            'TerminationTime': datetime(2015, 1, 1),
            'Status': 'RESERVED'|'ACTIVE'|'COMPLETED'|'TIMEDOUT',
            'IpAddress': 'string',
            'Port': 123
        },
    ]
}

Response Structure

  • (dict) --

    Represents the returned data in response to a request action.

    • PlayerSessions (list) --

      Collection of player session objects created for the added players.

      • (dict) --

        Properties describing a player session.

        • PlayerSessionId (string) --

          Unique identifier for a player session.

        • PlayerId (string) --

          Unique identifier for a player.

        • GameSessionId (string) --

          Unique identifier for a game session.

        • 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).

        • Status (string) --

          Current status of the player session. Possible player session states include the following:

          • RESERVED – The player session request has been received, but the player has not yet connected to the server process and/or been validated.

          • ACTIVE – The player has been validated by the server process and is currently connected.

          • COMPLETED – The player connection has been dropped.

          • TIMEDOUT – A player session request was received, but the player did not connect and/or was not validated within the time-out limit (60 seconds).

        • IpAddress (string) --

          Game session IP address. All player sessions reference the game session location.

        • Port (integer) --

          Port number for the game session. To connect to a GameLift server process, an app needs both the IP address and port number.

DescribeFleetUtilization (updated) Link ¶
Changes (response)
{'FleetUtilization': {'ActiveServerProcessCount': 'integer'}}

Retrieves utilization statistics for one or more fleets. You can request utilization data for all fleets, or specify a list of one or more fleet IDs. When requesting multiple fleets, use the pagination parameters to retrieve results as a set of sequential pages. If successful, a FleetUtilization object is returned for each requested fleet ID. When specifying a list of fleet IDs, utilization 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_utilization(
    FleetIds=[
        'string',
    ],
    Limit=123,
    NextToken='string'
)
type FleetIds

list

param FleetIds

Unique identifier for the fleet(s) you want to retrieve utilization data for. To request utilization data for all fleets, leave this parameter empty.

  • (string) --

type Limit

integer

param Limit

Maximum number of results to return. 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.

type NextToken

string

param NextToken

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.

rtype

dict

returns

Response Syntax

{
    'FleetUtilization': [
        {
            'FleetId': 'string',
            'ActiveServerProcessCount': 123,
            'ActiveGameSessionCount': 123,
            'CurrentPlayerSessionCount': 123,
            'MaximumPlayerSessionCount': 123
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    Represents the returned data in response to a request action.

    • FleetUtilization (list) --

      Collection of objects containing utilization information for each requested fleet ID.

      • (dict) --

        Current status of fleet utilization, including the number of game and player sessions being hosted.

        • FleetId (string) --

          Unique identifier for a fleet.

        • ActiveServerProcessCount (integer) --

          Number of server processes in an ACTIVE state currently running across all instances in the fleet

        • ActiveGameSessionCount (integer) --

          Number of active game sessions currently being hosted on all instances in the fleet.

        • CurrentPlayerSessionCount (integer) --

          Number of active player sessions currently being hosted on all instances in the fleet.

        • MaximumPlayerSessionCount (integer) --

          Maximum players allowed across all game sessions currently being hosted on all instances in the fleet.

    • 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.

DescribeGameSessionDetails (updated) Link ¶
Changes (response)
{'GameSessionDetails': {'GameSession': {'Port': 'integer'}}}

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'
)
type FleetId

string

param FleetId

Unique identifier for a fleet. Specify a fleet to retrieve information on all game sessions active on the fleet.

type GameSessionId

string

param GameSessionId

Unique identifier for a game session. Specify the game session to retrieve information on.

type AliasId

string

param AliasId

Unique identifier for a fleet alias. Specify an alias to retrieve information on all game sessions active on the fleet.

type StatusFilter

string

param StatusFilter

Game session status to filter results on. Possible game session states include ACTIVE, TERMINATED , ACTIVATING and TERMINATING (the last two are transitory).

type Limit

integer

param Limit

Maximum number of results to return. Use this parameter with NextToken to get results as a set of sequential pages.

type NextToken

string

param NextToken

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.

rtype

dict

returns

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',
                'Port': 123,
                '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 a 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 a server process requires to set up a game session. 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. To connect to a GameLift server process, an app needs both the IP address and port number.

          • Port (integer) --

            Port number for the game session. To connect to a GameLift server process, an app needs both the IP address and port number.

          • 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.

DescribeGameSessions (updated) Link ¶
Changes (response)
{'GameSessions': {'Port': 'integer'}}

Retrieves properties for one or more game sessions. This action can be used in several ways: (1) provide a GameSessionId to request properties for a specific game session; (2) provide 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 GameSession object is returned for each session matching the request.

Request Syntax

client.describe_game_sessions(
    FleetId='string',
    GameSessionId='string',
    AliasId='string',
    StatusFilter='string',
    Limit=123,
    NextToken='string'
)
type FleetId

string

param FleetId

Unique identifier for a fleet. Specify a fleet to retrieve information on all game sessions active on the fleet.

type GameSessionId

string

param GameSessionId

Unique identifier for a game session. Specify the game session to retrieve information on.

type AliasId

string

param AliasId

Unique identifier for a fleet alias. Specify an alias to retrieve information on all game sessions active on the fleet.

type StatusFilter

string

param StatusFilter

Game session status to filter results on. Possible game session states include ACTIVE , TERMINATED , ACTIVATING , and TERMINATING (the last two are transitory).

type Limit

integer

param Limit

Maximum number of results to return. Use this parameter with NextToken to get results as a set of sequential pages.

type NextToken

string

param NextToken

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.

rtype

dict

returns

Response Syntax

{
    'GameSessions': [
        {
            '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',
            'Port': 123,
            'PlayerSessionCreationPolicy': 'ACCEPT_ALL'|'DENY_ALL'
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    Represents the returned data in response to a request action.

    • GameSessions (list) --

      Collection of objects containing game session properties for each session matching the request.

      • (dict) --

        Properties describing a game session.

        • GameSessionId (string) --

          Unique identifier for a game session.

        • Name (string) --

          Descriptive label associated with a 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 a server process requires to set up a game session. 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. To connect to a GameLift server process, an app needs both the IP address and port number.

        • Port (integer) --

          Port number for the game session. To connect to a GameLift server process, an app needs both the IP address and port number.

        • PlayerSessionCreationPolicy (string) --

          Indicates whether or not the game session is accepting new players.

    • 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.

DescribePlayerSessions (updated) Link ¶
Changes (response)
{'PlayerSessions': {'Port': 'integer'}}

Retrieves properties for one or more player sessions. This action can be used in several ways: (1) provide a PlayerSessionId parameter to request properties for a specific player session; (2) provide a GameSessionId parameter to request properties for all player sessions in the specified game session; (3) provide a PlayerId parameter to request properties for all player sessions of a specified player.

To get game session record(s), specify only one of the following: a player session ID, a game session ID, or a player ID. You can filter this request by player session status. Use the pagination parameters to retrieve results as a set of sequential pages. If successful, a PlayerSession object is returned for each session matching the request.

Request Syntax

client.describe_player_sessions(
    GameSessionId='string',
    PlayerId='string',
    PlayerSessionId='string',
    PlayerSessionStatusFilter='string',
    Limit=123,
    NextToken='string'
)
type GameSessionId

string

param GameSessionId

Unique identifier for a game session.

type PlayerId

string

param PlayerId

Unique identifier for a player.

type PlayerSessionId

string

param PlayerSessionId

Unique identifier for a player session.

type PlayerSessionStatusFilter

string

param PlayerSessionStatusFilter

Player session status to filter results on. Possible player session states include the following:

  • RESERVED – The player session request has been received, but the player has not yet connected to the server process and/or been validated.

  • ACTIVE – The player has been validated by the server process and is currently connected.

  • COMPLETED – The player connection has been dropped.

  • TIMEDOUT – A player session request was received, but the player did not connect and/or was not validated within the time-out limit (60 seconds).

type Limit

integer

param Limit

Maximum number of results to return. Use this parameter with NextToken to get results as a set of sequential pages. If a player session ID is specified, this parameter is ignored.

type NextToken

string

param NextToken

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. If a player session ID is specified, this parameter is ignored.

rtype

dict

returns

Response Syntax

{
    'PlayerSessions': [
        {
            'PlayerSessionId': 'string',
            'PlayerId': 'string',
            'GameSessionId': 'string',
            'FleetId': 'string',
            'CreationTime': datetime(2015, 1, 1),
            'TerminationTime': datetime(2015, 1, 1),
            'Status': 'RESERVED'|'ACTIVE'|'COMPLETED'|'TIMEDOUT',
            'IpAddress': 'string',
            'Port': 123
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    Represents the returned data in response to a request action.

    • PlayerSessions (list) --

      Collection of objects containing properties for each player session that matches the request.

      • (dict) --

        Properties describing a player session.

        • PlayerSessionId (string) --

          Unique identifier for a player session.

        • PlayerId (string) --

          Unique identifier for a player.

        • GameSessionId (string) --

          Unique identifier for a game session.

        • 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).

        • Status (string) --

          Current status of the player session. Possible player session states include the following:

          • RESERVED – The player session request has been received, but the player has not yet connected to the server process and/or been validated.

          • ACTIVE – The player has been validated by the server process and is currently connected.

          • COMPLETED – The player connection has been dropped.

          • TIMEDOUT – A player session request was received, but the player did not connect and/or was not validated within the time-out limit (60 seconds).

        • IpAddress (string) --

          Game session IP address. All player sessions reference the game session location.

        • Port (integer) --

          Port number for the game session. To connect to a GameLift server process, an app needs both the IP address and port number.

    • 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.

UpdateGameSession (updated) Link ¶
Changes (response)
{'GameSession': {'Port': 'integer'}}

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'
)
type GameSessionId

string

param GameSessionId

[REQUIRED]

Unique identifier for a game session. Specify the game session you want to update.

type MaximumPlayerSessionCount

integer

param MaximumPlayerSessionCount

Maximum number of players that can be simultaneously connected to the game session.

type Name

string

param Name

Descriptive label associated with a game session. Session names do not need to be unique.

type PlayerSessionCreationPolicy

string

param PlayerSessionCreationPolicy

Policy determining whether or not the game session accepts new players.

type ProtectionPolicy

string

param ProtectionPolicy

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.

rtype

dict

returns

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',
        'Port': 123,
        '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 a 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 a server process requires to set up a game session. 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. To connect to a GameLift server process, an app needs both the IP address and port number.

      • Port (integer) --

        Port number for the game session. To connect to a GameLift server process, an app needs both the IP address and port number.

      • PlayerSessionCreationPolicy (string) --

        Indicates whether or not the game session is accepting new players.