Add locations that can host stream sessions. You configure locations and their corresponding capacity for each stream group. Creating a stream group in a location that's nearest to your end users can help minimize latency and improve quality.
This operation provisions stream capacity at the specified locations. By default, all locations have 1 or 2 capacity, depending on the stream class option: 2 for 'High' and 1 for 'Ultra' and 'Win2022'. This operation also copies the content files of all associated applications to an internal S3 bucket at each location. This allows Amazon GameLift Streams to host performant stream sessions.
Request Syntax
POST /streamgroups/Identifier/locations HTTP/1.1
Content-type: application/json
{
"LocationConfigurations": [
{
"AlwaysOnCapacity": number,
"LocationName": "string",
"OnDemandCapacity": number
}
]
}URI Request Parameters
The request uses the following URI parameters.
- Identifier
-
A stream group to add the specified locations to.
This value is a Amazon Resource Name (ARN) that uniquely identifies the stream group resource. Format example:
sg-1AB2C3De4.Length Constraints: Minimum length of 1. Maximum length of 128.
Pattern:
^(^[a-zA-Z0-9-]+$)|(^arn:aws:gameliftstreams:([^: ]*):([0-9]{12}):([^: ]*)$)$Required: Yes
Request Body
The request accepts the following data in JSON format.
- LocationConfigurations
-
A set of one or more locations and the streaming capacity for each location.
Type: Array of LocationConfiguration objects
Array Members: Minimum number of 1 item. Maximum number of 100 items.
Required: Yes
Response Syntax
HTTP/1.1 200
Content-type: application/json
{
"Identifier": "string",
"Locations": [
{
"AllocatedCapacity": number,
"AlwaysOnCapacity": number,
"IdleCapacity": number,
"LocationName": "string",
"OnDemandCapacity": number,
"RequestedCapacity": number,
"Status": "string"
}
]
}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.
- Identifier
-
This value is the Amazon Resource Name (ARN) that uniquely identifies the stream group resource. Format example:
sg-1AB2C3De4.Type: String
Length Constraints: Minimum length of 1. Maximum length of 128.
Pattern:
^(^[a-zA-Z0-9-]+$)|(^arn:aws:gameliftstreams:([^: ]*):([0-9]{12}):([^: ]*)$)$ - Locations
-
This value is set of locations, including their name, current status, and capacities.
A location can be in one of the following states:
-
ACTIVATING: Amazon GameLift Streams is preparing the location. You cannot stream from, scale the capacity of, or remove this location yet.
-
ACTIVE: The location is provisioned with initial capacity. You can now stream from, scale the capacity of, or remove this location.
-
ERROR: Amazon GameLift Streams failed to set up this location. The StatusReason field describes the error. You can remove this location and try to add it again.
-
REMOVING: Amazon GameLift Streams is working to remove this location. It releases all provisioned capacity for this location in this stream group.
Type: Array of LocationState objects
-
Errors
For information about the errors that are common to all actions, see Common Errors.
- AccessDeniedException
-
You don't have the required permissions to access this Amazon GameLift Streams resource. Correct the permissions before you try again.
HTTP Status Code: 403
- InternalServerException
-
The service encountered an internal error and is unable to complete the request.
HTTP Status Code: 500
- ResourceNotFoundException
-
The resource specified in the request was not found. Correct the request before you try again.
HTTP Status Code: 404
- ServiceQuotaExceededException
-
The request would cause the resource to exceed an allowed service quota. Resolve the issue before you try again.
HTTP Status Code: 402
- ThrottlingException
-
The request was denied due to request throttling. Retry the request after the suggested wait time.
HTTP Status Code: 429
- ValidationException
-
One or more parameter values in the request fail to satisfy the specified constraints. Correct the invalid parameter values before retrying the request.
HTTP Status Code: 400
Examples
CLI Example
The following example shows how to add multiple locations to the stream group.
Sample Request
aws gameliftstreams add-stream-group-locations \
--identifier arn:aws:gameliftstreams:us-west-2:123456789012:streamgroup/sg-1AB2C3De4 \
--location-configurations '[{"LocationName": "us-east-1", "AlwaysOnCapacity": 2, "OnDemandCapacity": 2}]'See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
