Request Syntax Request Parameters Response Syntax Response Elements Errors Examples See Also

CreateGameSessionQueue

Creates a placement queue that processes requests for new game sessions. A queue uses FleetIQ algorithms to determine the best placement locations and find an available game server there, then prompts the game server process to start a new game session.

A game session queue is configured with a set of destinations (Amazon GameLift fleets or aliases), which determine the locations where the queue can place new game sessions. These destinations can span multiple fleet types (Spot and On-Demand), instance types, and AWS Regions. If the queue includes multi-location fleets, the queue is able to place game sessions in all of a fleet's remote locations. You can opt to filter out individual locations if needed.

The queue configuration also determines how FleetIQ selects the best available placement for a new game session. Before searching for an available game server, FleetIQ first prioritizes the queue's destinations and locations, with the best placement locations on top. You can set up the queue to use the FleetIQ default prioritization or provide an alternate set of priorities.

To create a new queue, provide a name, timeout value, and a list of destinations. Optionally, specify a sort configuration and/or a filter, and define a set of latency cap policies. You can also include the ARN for an Amazon Simple Notification Service (SNS) topic to receive notifications of game session placement activity. Notifications using SNS or CloudWatch events is the preferred way to track placement activity.

If successful, a new GameSessionQueue object is returned with an assigned queue ARN. New game session requests, which are submitted to queue with StartGameSessionPlacement or StartMatchmaking, reference a queue's name or ARN.

Learn more

Design a game session queue

Create a game session queue

Request Syntax


{
   "CustomEventData": "string",
   "Destinations": [ 
      { 
         "DestinationArn": "string"
      }
   ],
   "FilterConfiguration": { 
      "AllowedLocations": [ "string" ]
   },
   "Name": "string",
   "NotificationTarget": "string",
   "PlayerLatencyPolicies": [ 
      { 
         "MaximumIndividualPlayerLatencyMilliseconds": number,
         "PolicyDurationSeconds": number
      }
   ],
   "PriorityConfiguration": { 
      "LocationOrder": [ "string" ],
      "PriorityOrder": [ "string" ]
   },
   "Tags": [ 
      { 
         "Key": "string",
         "Value": "string"
      }
   ],
   "TimeoutInSeconds": number
}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

Note

In the following list, the required parameters are described first.

Name

A descriptive label that is associated with game session queue. Queue names must be unique within each Region.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9-]+

Required: Yes

CustomEventData

Information to be added to all events that are related to this game session queue.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 256.

Pattern: [\s\S]*

Required: No

Destinations

A list of fleets and/or fleet aliases that can be used to fulfill game session placement requests in the queue. Destinations are identified by either a fleet ARN or a fleet alias ARN, and are listed in order of placement preference.

Type: Array of GameSessionQueueDestination objects

Required: No

FilterConfiguration

A list of locations where a queue is allowed to place new game sessions. Locations are specified in the form of AWS Region codes, such as us-west-2. If this parameter is not set, game sessions can be placed in any queue location.

Type: FilterConfiguration object

Required: No

NotificationTarget

An SNS topic ARN that is set up to receive game session placement notifications. See Setting up notifications for game session placement.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 300.

Pattern: [a-zA-Z0-9:_-]*(\.fifo)?

Required: No

PlayerLatencyPolicies

A set of policies that act as a sliding cap on player latency. FleetIQ works to deliver low latency for most players in a game session. These policies ensure that no individual player can be placed into a game with unreasonably high latency. Use multiple policies to gradually relax latency requirements a step at a time. Multiple policies are applied based on their maximum allowed latency, starting with the lowest value.

Type: Array of PlayerLatencyPolicy objects

Required: No

PriorityConfiguration

Custom settings to use when prioritizing destinations and locations for game session placements. This configuration replaces the FleetIQ default prioritization process. Priority types that are not explicitly named will be automatically applied at the end of the prioritization process.

Type: PriorityConfiguration object

Required: No

Tags

A list of labels to assign to the new game session queue resource. Tags are developer-defined key-value pairs. Tagging AWS resources are useful for resource management, access management and cost allocation. For more information, see Tagging AWS Resources in the AWS General Reference.

Type: Array of Tag objects

Array Members: Minimum number of 0 items. Maximum number of 200 items.

Required: No

TimeoutInSeconds

The maximum time, in seconds, that a new game session placement request remains in the queue. When a request exceeds this time, the game session placement changes to a TIMED_OUT status. By default, this property is set to 600.

Type: Integer

Valid Range: Minimum value of 0.

Required: No

Response Syntax


{
   "GameSessionQueue": { 
      "CustomEventData": "string",
      "Destinations": [ 
         { 
            "DestinationArn": "string"
         }
      ],
      "FilterConfiguration": { 
         "AllowedLocations": [ "string" ]
      },
      "GameSessionQueueArn": "string",
      "Name": "string",
      "NotificationTarget": "string",
      "PlayerLatencyPolicies": [ 
         { 
            "MaximumIndividualPlayerLatencyMilliseconds": number,
            "PolicyDurationSeconds": number
         }
      ],
      "PriorityConfiguration": { 
         "LocationOrder": [ "string" ],
         "PriorityOrder": [ "string" ]
      },
      "TimeoutInSeconds": number
   }
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

GameSessionQueue

An object that describes the newly created game session queue.

Type: GameSessionQueue object

Errors

For information about the errors that are common to all actions, see Common Errors.

InternalServiceException

The service encountered an unrecoverable internal failure while processing the request. Clients can retry such requests immediately or after a waiting period.

HTTP Status Code: 500

InvalidRequestException

One or more parameter values in the request are invalid. Correct the invalid parameter values before retrying.

HTTP Status Code: 400

LimitExceededException

The requested operation would cause the resource to exceed the allowed service limit. Resolve the issue before retrying.

HTTP Status Code: 400

NotFoundException

The requested resources was not found. The resource was either not created yet or deleted.

HTTP Status Code: 400

TaggingFailedException

The requested tagging operation did not succeed. This may be due to invalid tag format or the maximum tag limit may have been exceeded. Resolve the issue before retrying.

HTTP Status Code: 400

UnauthorizedException

The client failed authentication. Clients should not retry such requests.

HTTP Status Code: 400

Examples

Create and configure a game session queue

In this example, we want to create a game session queue with two single-location destinations, each residing in different Regions. We configure the queue so that requests for new game sessions expire after 10 minutes. The queue will process game session requests with player latency data, so we provide a set of latency cap polices that initially start at 100mm and then relax to 200ms after one minute. We opt to use the default sort approach for FleetIQ.

Sample Request


{
    "Name": "matchmaker-queue",
    "Destinations": [
        { "DestinationArn": "arn:aws:gamelift:us-west-2::fleet/fleet-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" },
        { "DestinationArn": "arn:aws:gamelift:sa-east-1::fleet/fleet-5c6d3c4d-5e6f-7a8b-9a0b-1e2f3a4b5a2b" }
    ],
    "NotificationTarget": "arn:aws:sns:us-west-2:111122223333:My_Placement_SNS_Topic",
    "PlayerLatencyPolicies": [ 
        { "MaximumIndividualPlayerLatencyMilliseconds": 200 },
        { "MaximumIndividualPlayerLatencyMilliseconds": 100, "PolicyDurationSeconds": 60 }
    ],
    "TimeoutInSeconds": 600
}

Sample Response


{
    "GameSessionQueue": {
        "Name": "matchmaker-queue",
        "GameSessionQueueArn": "arn:aws:gamelift:us-west-2:111122223333:gamesessionqueue/matchmaker-queue",
        "TimeoutInSeconds": 600,
        "NotificationTarget": "arn:aws:sns:us-west-2:111122223333:My_Placement_SNS_Topic",
        "PlayerLatencyPolicies": [
            {
                "MaximumIndividualPlayerLatencyMilliseconds": 100, 
                "PolicyDurationSeconds": 60
            }, 
            {
                "MaximumIndividualPlayerLatencyMilliseconds": 200
            }
        ],
        "Destinations": [
            {"DestinationArn": "arn:aws:gamelift:us-west-2::fleet/fleet-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"},
            {"DestinationArn": "arn:aws:gamelift:us-east-1::fleet/fleet-5c6d3c4d-5e6f-7a8b-9c0d-1e2f3a4b5a2b"}
        ]
    }
}

Create a game session queue with multi-location fleets

In this example, we want to create a game session queue to place game sessions with two multi-location Spot fleets and one single-location On-Demand fleet. The multi-location fleets have remote locations in (us-west-1, us-east-2, sa-east-1).

We also want to change how FleetIQ prioritizes destinations and locations for placement. We opt to have FleetIQ prioritize by location first (with a custom location order provided), and then by destination list order. Based on our priority configuration, the queue will always try to place game sessions in the us-west-1 remote location of the first listed destination fleet. If no game servers are available there, the queue will try to place in the us-west-1 home Region of the second listed destination fleet, and so on.

Sample Request


{
    "Name": "matchmaker-queue",
    "Destinations": [
        { "DestinationArn": "arn:aws:gamelift:us-west-2::fleet/fleet-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" },
        { "DestinationArn": "arn:aws:gamelift:us-west-1::fleet/fleet-2a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d" },
        { "DestinationArn": "arn:aws:gamelift:us-west-2::fleet/fleet-5c6d3c4d-5e6f-7a8b-9a0b-1e2f3a4b5a2b" }
    ],
    "NotificationTarget": "arn:aws:sns:us-west-2:111122223333:My_Placement_SNS_Topic",
    "PriorityConfiguration": {
        "PriorityOrder": "LOCATION,DESTINATION",
        "LocationOrder": "us-west-1,us-west-2,us-east-2, sa-east-1"
    },
    "TimeoutInSeconds": 600
}

Sample Response


{
    "GameSessionQueue": {
        "Name": "matchmaker-queue",
        "GameSessionQueueArn": "arn:aws:gamelift:us-west-2:111122223333:gamesessionqueue/matchmaker-queue",
        "TimeoutInSeconds": 600,
        "Destinations": [
            { "DestinationArn": "arn:aws:gamelift:us-west-2::fleet/fleet-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" },
            { "DestinationArn": "arn:aws:gamelift:us-west-1::fleet/fleet-2a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d" },
            { "DestinationArn": "arn:aws:gamelift:us-west-2::fleet/fleet-5c6d3c4d-5e6f-7a8b-9a0b-1e2f3a4b5a2b" }
        ],
        "PriorityConfiguration": {
            "PriorityOrder": "LOCATION,DESTINATION",
            "LocationOrder": "us-west-1,us-west-2,us-east-2, sa-east-1"
        },
        "NotificationTarget": "arn:aws:sns:us-west-2:111122223333:My_Placement_SNS_Topic",
    }
}