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
Related actions
CreateGameSessionQueue | DescribeGameSessionQueues | UpdateGameSessionQueue | DeleteGameSessionQueue | All APIs by task
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 enforce a sliding cap on player latency when processing game sessions placement requests. Use multiple policies to gradually relax the cap over time if Amazon GameLift can't make a placement. Policies are evaluated in order starting with the lowest maximum latency 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.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",
}
}
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: