Skip to main content

applications

Creates, updates, deletes, gets or lists an applications resource.

Overview​

Nameapplications
TypeResource
Idaws.gameliftstreams.applications

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
application_log_output_uristringAn Amazon S3 URI to a bucket where you would like Amazon GameLift Streams to save application logs. Required if you specify one or more ApplicationLogPaths. (pattern: <code>$|^s3:​//([a-zA-Z0-9][a-zA-Z0-9.-]{1,61}[a-zA-Z0-9])(/[a-zA-Z0-9.-]+)*/?</code>)
application_log_pathsarrayLocations of log files that your content generates during a stream session. Amazon GameLift Streams uploads log files to the Amazon S3 bucket that you specify in ApplicationLogOutputUri at the end of a stream session. To retrieve stored log files, call GetStreamSession and get the LogFileLocationUri.
application_source_uristringThe original Amazon S3 location of uploaded stream content for the application.
arnstringThe Amazon Resource Name (ARN) that's assigned to an application resource and uniquely identifies it across all Amazon Web Services Regions. Format is arn:aws:gameliftstreams:[AWS Region]:[AWS account]:application/[resource ID]. (pattern: <code>(^[a-zA-Z0-9-]+$)|(^arn:aws:gameliftstreams:([^: ]):([0-9]{12}):([^: ])$)</code>)
associated_stream_groupsarrayA set of stream groups that this application is associated with. You can use any of these stream groups to stream your application. This value is a set of Amazon Resource Names (ARNs) that uniquely identify stream group resources. Example ARN: arn:aws:gameliftstreams:us-west-2:111122223333:streamgroup/sg-1AB2C3De4.
created_atstring (date-time)A timestamp that indicates when this resource was created. Timestamps are expressed using in ISO8601 format, such as: 2022-12-27T22:29:40+00:00 (UTC).
descriptionstringA human-readable label for the application. You can edit this value. (pattern: <code>[a-zA-Z0-9-.!+@/][a-zA-Z0-9-.!+@/ ]*</code>)
executable_pathstringThe relative path and file name of the executable file that launches the content for streaming.
idstringA unique ID value that is assigned to the resource when it's created. Format example: a-9ZY8X7Wv6. (pattern: <code>[a-zA-Z0-9-]+</code>)
last_updated_atstring (date-time)A timestamp that indicates when this resource was last updated. Timestamps are expressed using in ISO8601 format, such as: 2022-12-27T22:29:40+00:00 (UTC).
replication_statusesarrayA set of replication statuses for each location.
runtime_environmentobjectConfiguration settings that identify the operating system for an application resource. This can also include a compatibility layer and other drivers. A runtime environment can be one of the following: For Linux applications Ubuntu 22.04 LTS (Type=UBUNTU, Version=22_04_LTS) For Windows applications Microsoft Windows Server 2022 Base (Type=WINDOWS, Version=2022) Proton 10.0-4 (Type=PROTON, Version=20260204) Proton 9.0-2 (Type=PROTON, Version=20250516) Proton 8.0-5 (Type=PROTON, Version=20241007) Proton 8.0-2c (Type=PROTON, Version=20230704)
statusstringThe current status of the application resource. Possible statuses include the following: INITIALIZED: Amazon GameLift Streams has received the request and is initiating the work flow to create an application. PROCESSING: The create application work flow is in process. Amazon GameLift Streams is copying the content and caching for future deployment in a stream group. READY: The application is ready to deploy in a stream group. ERROR: An error occurred when setting up the application. See StatusReason for more information. DELETING: Amazon GameLift Streams is in the process of deleting the application. (INITIALIZED, PROCESSING, READY, DELETING, ERROR)
status_reasonstringA short description of the status reason when the application is in ERROR status. (internalError, accessDenied, sourceModified)

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
get_applicationselectidentifier, regionRetrieves properties for an Amazon GameLift Streams application resource. Specify the ID of the application that you want to retrieve. If the operation is successful, it returns properties for the requested application.
list_applicationsselectregionNextToken, MaxResultsRetrieves a list of all Amazon GameLift Streams applications that are associated with the Amazon Web Services account in use. This operation returns applications in all statuses, in no particular order. You can paginate the results as needed.
create_applicationinsertregion, RuntimeEnvironment, ExecutablePath, ApplicationSourceUriCreates an application resource in Amazon GameLift Streams, which specifies the application content you want to stream, such as a game build or other software, and configures the settings to run it. Before you create an application, upload your application content files to an Amazon Simple Storage Service (Amazon S3) bucket. For more information, see Getting Started in the Amazon GameLift Streams Developer Guide. Make sure that your files in the Amazon S3 bucket are the correct version you want to use. If you change the files at a later time, you will need to create a new Amazon GameLift Streams application. Creating an application is the only time Amazon GameLift Streams accesses your Amazon S3 bucket. After the application reaches READY status, you can delete the original files from your Amazon S3 bucket without affecting the application. If the request is successful, Amazon GameLift Streams begins to create an application and sets the status to INITIALIZED. When an application reaches READY status, you can use the application to set up stream groups and start streams. To track application status, call GetApplication.
associate_applicationsupdateidentifier, region, ApplicationIdentifiersWhen you associate, or link, an application with a stream group, then Amazon GameLift Streams can launch the application using the stream group's allocated compute resources. The stream group must be in ACTIVE status. You can reverse this action by using DisassociateApplications. If a stream group does not already have a linked application, Amazon GameLift Streams will automatically assign the first application provided in ApplicationIdentifiers as the default.
update_applicationupdateidentifier, regionUpdates the mutable configuration settings for a Amazon GameLift Streams application resource. You can change the Description, ApplicationLogOutputUri, and ApplicationLogPaths. To update application settings, specify the application ID and provide the new values. If the operation is successful, it returns the complete updated set of settings for the application.
delete_applicationdeleteidentifier, regionPermanently deletes an Amazon GameLift Streams application resource. This also deletes the application content files stored with Amazon GameLift Streams. However, this does not delete the original files that you uploaded to your Amazon S3 bucket; you can delete these any time after Amazon GameLift Streams creates an application, which is the only time Amazon GameLift Streams accesses your Amazon S3 bucket. You can only delete an application that meets the following conditions: The application is in READY or ERROR status. You cannot delete an application that's in PROCESSING or INITIALIZED status. The application is not the default application of any stream groups. You must first delete the stream group by using DeleteStreamGroup. The application is not linked to any stream groups. You must first unlink the stream group by using DisassociateApplications. An application is not streaming in any ongoing stream session. You must wait until the client ends the stream session or call TerminateStreamSession to end the stream. If any active stream groups exist for this application, this request returns a ValidationException.
disassociate_applicationsexecidentifier, region, ApplicationIdentifiersWhen you disassociate, or unlink, an application from a stream group, you can no longer stream this application by using that stream group's allocated compute resources. Any streams in process will continue until they terminate, which helps avoid interrupting an end-user's stream. Amazon GameLift Streams will not initiate new streams in the stream group using the disassociated application. The disassociate action does not affect the stream capacity of a stream group. To disassociate an application, the stream group must be in ACTIVE status. If you disassociate the default application, Amazon GameLift Streams will automatically choose a new default application from the remaining associated applications. To change which application is the default application, call UpdateStreamGroup and specify a new DefaultApplicationIdentifier.
start_stream_sessionexecidentifier, region, SignalRequest, ApplicationIdentifierThis action initiates a new stream session and outputs connection information that clients can use to access the stream. A stream session refers to an instance of a stream that Amazon GameLift Streams transmits from the server to the end-user. A stream session runs on a compute resource that a stream group has allocated. The start stream session process works as follows: Prerequisites: You must have a stream group in ACTIVE status You must have idle or on-demand capacity in a stream group in the location you want to stream from You must have at least one application associated to the stream group (use AssociateApplications if needed) Start stream request: Your backend server calls StartStreamSession to initiate connection Amazon GameLift Streams creates the stream session resource, assigns an Amazon Resource Name (ARN) value, and begins searching for available stream capacity to run the stream Session transitions to ACTIVATING status Placement completion: If Amazon GameLift Streams is successful in finding capacity for the stream, the stream session status changes to ACTIVE status and StartStreamSession returns stream connection information If Amazon GameLift Streams was not successful in finding capacity within the placement timeout period (defined according to the capacity type and platform type), the stream session status changes to ERROR status and StartStreamSession returns a StatusReason of placementTimeout Connection completion: Provide the new connection information to the requesting client Client must establish connection within ConnectionTimeoutSeconds (specified in StartStreamSession parameters) Session terminates automatically if client fails to connect in time For more information about the stream session lifecycle, see Stream sessions in the Amazon GameLift Streams Developer Guide. Timeouts to be aware of that affect a stream session: Placement timeout: The amount of time that Amazon GameLift Streams has to find capacity for a stream request. Placement timeout varies based on the capacity type used to fulfill your stream request: Always-on capacity: 75 seconds On-demand capacity: Linux/Proton runtimes: 90 seconds Windows runtime: 10 minutes Connection timeout: The amount of time that Amazon GameLift Streams waits for a client to connect to a stream session in ACTIVE status, or reconnect to a stream session in PENDING_CLIENT_RECONNECTION status, the latter of which occurs when a client disconnects or loses connection from a stream session. If no client connects before the timeout, Amazon GameLift Streams terminates the stream session. This value is specified by ConnectionTimeoutSeconds in the StartStreamSession parameters. Maximum session length: A stream session will be terminated after this amount of time has elapsed since it started, regardless of any existing client connections. This value is specified by SessionLengthSeconds in the StartStreamSession parameters. To start a new stream session, specify a stream group ID and application ID, along with the transport protocol and signal request to use with the stream session. For stream groups that have multiple locations, provide a set of locations ordered by priority using a Locations parameter. Amazon GameLift Streams will start a single stream session in the next available location. An application must be finished replicating to a remote location before the remote location can host a stream. To reconnect to a stream session after a client disconnects or loses connection, use CreateStreamSessionConnection.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
identifierstringThe stream group to run this stream session with. This value is an Amazon Resource Name (ARN) or ID that uniquely identifies the stream group resource. Example ARN: arn:aws:gameliftstreams:us-west-2:111122223333:streamgroup/sg-1AB2C3De4. Example ID: sg-1AB2C3De4.
regionstringAWS region (default: us-east-1)
MaxResultsintegerThe number of results to return. Use this parameter with NextToken to return results in sequential pages. Default value is 25.
NextTokenstringThe token that marks the start of the next set of results. Use this token when you retrieve results as sequential pages. To get the first page of results, omit a token value. To get the remaining pages, provide the token returned with the previous result set.

SELECT examples​

Retrieves properties for an Amazon GameLift Streams application resource. Specify the ID of the application that you want to retrieve. If the operation is successful, it returns properties for the requested application.

SELECT
application_log_output_uri,
application_log_paths,
application_source_uri,
arn,
associated_stream_groups,
created_at,
description,
executable_path,
id,
last_updated_at,
replication_statuses,
runtime_environment,
status,
status_reason
FROM aws.gameliftstreams.applications
WHERE identifier = '{{ identifier }}' -- required
AND region = '{{ region }}' -- required
;

INSERT examples​

Creates an application resource in Amazon GameLift Streams, which specifies the application content you want to stream, such as a game build or other software, and configures the settings to run it. Before you create an application, upload your application content files to an Amazon Simple Storage Service (Amazon S3) bucket. For more information, see Getting Started in the Amazon GameLift Streams Developer Guide. Make sure that your files in the Amazon S3 bucket are the correct version you want to use. If you change the files at a later time, you will need to create a new Amazon GameLift Streams application. Creating an application is the only time Amazon GameLift Streams accesses your Amazon S3 bucket. After the application reaches READY status, you can delete the original files from your Amazon S3 bucket without affecting the application. If the request is successful, Amazon GameLift Streams begins to create an application and sets the status to INITIALIZED. When an application reaches READY status, you can use the application to set up stream groups and start streams. To track application status, call GetApplication.

INSERT INTO aws.gameliftstreams.applications (
Description,
RuntimeEnvironment,
ExecutablePath,
ApplicationSourceUri,
ApplicationLogPaths,
ApplicationLogOutputUri,
Tags,
ClientToken,
region
)
SELECT 
'{{ Description }}',
'{{ RuntimeEnvironment }}' /* required */,
'{{ ExecutablePath }}' /* required */,
'{{ ApplicationSourceUri }}' /* required */,
'{{ ApplicationLogPaths }}',
'{{ ApplicationLogOutputUri }}',
'{{ Tags }}',
'{{ ClientToken }}',
'{{ region }}'
RETURNING
application_log_output_uri,
application_log_paths,
application_source_uri,
arn,
associated_stream_groups,
created_at,
description,
executable_path,
id,
last_updated_at,
replication_statuses,
runtime_environment,
status,
status_reason
;

UPDATE examples​

When you associate, or link, an application with a stream group, then Amazon GameLift Streams can launch the application using the stream group's allocated compute resources. The stream group must be in ACTIVE status. You can reverse this action by using DisassociateApplications. If a stream group does not already have a linked application, Amazon GameLift Streams will automatically assign the first application provided in ApplicationIdentifiers as the default.

UPDATE aws.gameliftstreams.applications
SET 
ApplicationIdentifiers = '{{ ApplicationIdentifiers }}'
WHERE 
identifier = '{{ identifier }}' --required
AND region = '{{ region }}' --required
AND ApplicationIdentifiers = '{{ ApplicationIdentifiers }}' --required
RETURNING
application_arns,
arn;

DELETE examples​

Permanently deletes an Amazon GameLift Streams application resource. This also deletes the application content files stored with Amazon GameLift Streams. However, this does not delete the original files that you uploaded to your Amazon S3 bucket; you can delete these any time after Amazon GameLift Streams creates an application, which is the only time Amazon GameLift Streams accesses your Amazon S3 bucket. You can only delete an application that meets the following conditions: The application is in READY or ERROR status. You cannot delete an application that's in PROCESSING or INITIALIZED status. The application is not the default application of any stream groups. You must first delete the stream group by using DeleteStreamGroup. The application is not linked to any stream groups. You must first unlink the stream group by using DisassociateApplications. An application is not streaming in any ongoing stream session. You must wait until the client ends the stream session or call TerminateStreamSession to end the stream. If any active stream groups exist for this application, this request returns a ValidationException.

DELETE FROM aws.gameliftstreams.applications
WHERE identifier = '{{ identifier }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods​

When you disassociate, or unlink, an application from a stream group, you can no longer stream this application by using that stream group's allocated compute resources. Any streams in process will continue until they terminate, which helps avoid interrupting an end-user's stream. Amazon GameLift Streams will not initiate new streams in the stream group using the disassociated application. The disassociate action does not affect the stream capacity of a stream group. To disassociate an application, the stream group must be in ACTIVE status. If you disassociate the default application, Amazon GameLift Streams will automatically choose a new default application from the remaining associated applications. To change which application is the default application, call UpdateStreamGroup and specify a new DefaultApplicationIdentifier.

EXEC aws.gameliftstreams.applications.disassociate_applications 
@identifier='{{ identifier }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"ApplicationIdentifiers": "{{ ApplicationIdentifiers }}"
}'
;
Last updated on