Skip to main content

stream_sessions

Creates, updates, deletes, gets or lists a stream_sessions resource.

Overview​

Namestream_sessions
TypeResource
Idaws.gameliftstreams.stream_sessions

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
additional_environment_variablesobjectA set of options that you can use to control the stream session runtime environment, expressed as a set of key-value pairs. You can use this to configure the application or stream session details. You can also provide custom environment variables that Amazon GameLift Streams passes to your game client. If you want to debug your application with environment variables, we recommend that you do so in a local environment outside of Amazon GameLift Streams. For more information, refer to the Compatibility Guidance in the troubleshooting section of the Developer Guide. AdditionalEnvironmentVariables and AdditionalLaunchArgs have similar purposes. AdditionalEnvironmentVariables passes data using environment variables; while AdditionalLaunchArgs passes data using command-line arguments.
additional_launch_argsarrayA list of CLI arguments that are sent to the streaming server when a stream session launches. You can use this to configure the application or stream session details. You can also provide custom arguments that Amazon GameLift Streams passes to your game client. AdditionalEnvironmentVariables and AdditionalLaunchArgs have similar purposes. AdditionalEnvironmentVariables passes data using environment variables; while AdditionalLaunchArgs passes data using command-line arguments.
application_arnstringThe application streaming in this session. This value is an Amazon Resource Name (ARN) that uniquely identifies the application resource. Example ARN: arn:aws:gameliftstreams:us-west-2:111122223333:application/a-9ZY8X7Wv6. (pattern: <code>arn:aws:gameliftstreams:([^: ]):([0-9]{12}):([^: ])</code>)
arnstringThe Amazon Resource Name (ARN) that's assigned to a stream session resource. When combined with the stream group resource ID, this value uniquely identifies the stream session across all Amazon Web Services Regions. Format is arn:aws:gameliftstreams:[AWS Region]:[AWS account]:streamsession/[stream group resource ID]/[stream session resource ID]. (pattern: <code>arn:aws:gameliftstreams:([^: ]):([0-9]{12}):([^: ])</code>)
connection_timeout_secondsintegerThe length of time that Amazon GameLift Streams should wait for a client to connect or reconnect to the stream session. This time span starts when the stream session reaches ACTIVE or PENDING_CLIENT_RECONNECTION state. If no client connects (or reconnects) before the timeout, Amazon GameLift Streams terminates the stream session.
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 stream session. You can update this value at any time. (pattern: <code>[a-zA-Z0-9-.!+@/][a-zA-Z0-9-.!+@/ ]*</code>)
display_configurationobjectThe virtual monitor settings for a stream session, including the resolution. If not specified, the stream session uses the default resolution of 1920 × 1080.
export_files_metadataobjectProvides details about the stream session's exported files.
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).
locationstringThe location where Amazon GameLift Streams hosts and streams your application. For example, us-east-1. For a complete list of locations that Amazon GameLift Streams supports, refer to Regions, quotas, and limitations in the Amazon GameLift Streams Developer Guide. (pattern: <code>[a-zA-Z0-9-]+</code>)
log_file_location_uristringAccess location for log files that your content generates during a stream session. These log files are uploaded to cloud storage location at the end of a stream session. The Amazon GameLift Streams application resource defines which log files to upload.
performance_stats_configurationobjectThe performance stats configuration for the stream session
protocolstringThe data transfer protocol in use with the stream session. (WebRTC)
role_arnstringThe ARN of the AWS Identity and Access Management (IAM) role that Amazon GameLift Streams assumes on behalf of your application during the stream session. (pattern: <code>arn:aws[a-zA-Z-]*:iam::\d{12}:role/.+</code>)
session_length_secondsintegerThe maximum duration of a session. Amazon GameLift Streams will automatically terminate a session after this amount of time has elapsed, regardless of any existing client connections.
signal_requeststringThe WebRTC ICE offer string that a client generates to initiate a connection to the stream session.
signal_responsestringThe WebRTC answer string that the stream server generates in response to the SignalRequest.
statusstringThe current status of the stream session. A stream session is ready for a client to connect when in ACTIVE status. ACTIVATING: The stream session is starting and preparing to stream. ACTIVE: The stream session is ready and waiting for a client connection. A client has ConnectionTimeoutSeconds (specified in StartStreamSession) from when the session reaches ACTIVE state to establish a connection. If no client connects within this timeframe, the session automatically terminates. CONNECTED: The stream session has a connected client. A session will automatically terminate if there is no user input for 60 minutes, or if the maximum length of a session specified by SessionLengthSeconds in StartStreamSession is exceeded. ERROR: The stream session failed to activate. See StatusReason (returned by GetStreamSession and StartStreamSession) for more information. PENDING_CLIENT_RECONNECTION: A client has recently disconnected and the stream session is waiting for the client to reconnect. A client has ConnectionTimeoutSeconds (specified in StartStreamSession) from when the session reaches PENDING_CLIENT_RECONNECTION state to re-establish a connection. If no client connects within this timeframe, the session automatically terminates. RECONNECTING: A client has initiated a reconnect to a session that was in PENDING_CLIENT_RECONNECTION state. TERMINATING: The stream session is ending. TERMINATED: The stream session has ended. (ACTIVATING, ACTIVE, CONNECTED, PENDING_CLIENT_RECONNECTION, RECONNECTING, TERMINATING, TERMINATED, ERROR)
status_reasonstringA short description of the reason the stream session is in ERROR status or TERMINATED status. ERROR status reasons: applicationLogS3DestinationError: Could not write the application log to the Amazon S3 bucket that is configured for the streaming application. Make sure the bucket still exists. internalError: An internal service error occurred. Start a new stream session to continue streaming. invalidSignalRequest: The WebRTC signal request that was sent is not valid. When starting or reconnecting to a stream session, use generateSignalRequest in the Amazon GameLift Streams Web SDK to generate a new signal request. placementTimeout: Amazon GameLift Streams could not find available stream capacity to start a stream session. Increase the stream capacity in the stream group or wait until capacity becomes available. TERMINATED status reasons: apiTerminated: The stream session was terminated by an API call to TerminateStreamSession. applicationExit: The streaming application exited or crashed. The stream session was terminated because the application is no longer running. connectionTimeout: The stream session was terminated because the client failed to connect within the connection timeout period specified by ConnectionTimeoutSeconds. maxSessionLengthTimeout: The stream session was terminated because it exceeded the maximum session length timeout period specified by SessionLengthSeconds. reconnectionTimeout: The stream session was terminated because the client failed to reconnect within the reconnection timeout period specified by ConnectionTimeoutSeconds after losing connection. (internalError, invalidSignalRequest, placementTimeout, applicationLogS3DestinationError, assumeRoleFailed, applicationExit, connectionTimeout, reconnectionTimeout, maxSessionLengthTimeout, idleTimeout, apiTerminated)
stream_group_idstringThe unique identifier for the Amazon GameLift Streams stream group that is hosting the stream session. Format example: sg-1AB2C3De4. (pattern: <code>[a-zA-Z0-9-]+</code>)
user_idstringAn opaque, unique identifier for an end-user, defined by the developer. (pattern: <code>[-_a-zA-Z0-9/=+]*</code>)
web_sdk_protocol_urlstringThe URL of an S3 bucket that stores Amazon GameLift Streams WebSDK files. The URL is used to establish connection with the client.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
get_stream_sessionselectidentifier, stream_session_identifier, regionRetrieves properties for a Amazon GameLift Streams stream session resource. Specify the Amazon Resource Name (ARN) of the stream session that you want to retrieve and its stream group ARN. If the operation is successful, it returns properties for the requested resource.
list_stream_sessionsselectidentifier, regionStatus, ExportFilesStatus, NextToken, MaxResultsRetrieves a list of Amazon GameLift Streams stream sessions that a stream group is hosting. To retrieve stream sessions, specify the stream group, and optionally filter by stream session status. You can paginate the results as needed. This operation returns the requested stream sessions in no particular order.
create_stream_session_connectioninsertidentifier, stream_session_identifier, region, SignalRequestEnables clients to reconnect to a stream session while preserving all session state and data in the disconnected session. This reconnection process can be initiated when a stream session is in either PENDING_CLIENT_RECONNECTION or ACTIVE status. The process works as follows: Initial disconnect: When a client disconnects or loses connection, the stream session transitions from CONNECTED to PENDING_CLIENT_RECONNECTION Reconnection time window: Clients have ConnectionTimeoutSeconds (defined in StartStreamSession) to reconnect before session termination Your backend server must call CreateStreamSessionConnection to initiate reconnection Session transitions to RECONNECTING status Reconnection completion: On successful CreateStreamSessionConnection, session status changes to ACTIVE Provide the new connection information to the requesting client Client must establish connection within ConnectionTimeoutSeconds 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. To begin re-connecting to an existing stream session, specify the stream group ID and stream session ID that you want to reconnect to, and the signal request to use with the stream.
create_stream_session_admin_shellinsertidentifier, stream_session_identifier, regionCreates an administrative terminal session with full access to the live runtime environment of the Amazon GameLift Streams stream session. Use the returned credentials (SessionId, StreamUrl and TokenValue) with the Amazon Web Services Systems Manager Session Manager plugin for the CLI to access the terminal session. The stream session must be in one of the following statuses: ACTIVE, CONNECTED, PENDING_CLIENT_RECONNECTION, or RECONNECTING. The StreamUrl is valid for 60 seconds. After it expires, call this operation again to get a new URL. The returned credentials grant full access to the live runtime environment of the Amazon GameLift Streams stream session. The operator who connects to the terminal session has the same level of access that your Amazon GameLift Streams applications have, including potentially user input, screen images, and application data files. Grant permissions to call this operation only to trusted IAM identities that require live runtime environment access.
terminate_stream_sessiondeleteidentifier, stream_session_identifier, regionPermanently terminates an active stream session. When called, the stream session status changes to TERMINATING. You can terminate a stream session in any status except ACTIVATING. If the stream session is in ACTIVATING status, an exception is thrown.
export_stream_session_filesexecidentifier, stream_session_identifier, region, OutputUriExport the files that your application modifies or generates in a stream session, which can help you debug or verify your application. When your application runs, it generates output files such as logs, diagnostic information, crash dumps, save files, user data, screenshots, and so on. The files can be defined by the engine or frameworks that your application uses, or information that you've programmed your application to output. You can only call this action on a stream session that is in progress, specifically in one of the following statuses ACTIVE, CONNECTED, PENDING_CLIENT_RECONNECTION, and RECONNECTING. You must provide an Amazon Simple Storage Service (Amazon S3) bucket to store the files in. When the session ends, Amazon GameLift Streams produces a compressed folder that contains all of the files and directories that were modified or created by the application during the stream session. AWS uses your security credentials to authenticate and authorize access to your Amazon S3 bucket. Amazon GameLift Streams collects the following generated and modified files. Find them in the corresponding folders in the .zip archive. application/: The folder where your application or game is stored. profile/: The user profile folder. temp/: The system temp folder. To verify the status of the exported files, use GetStreamSession. To delete the files, delete the object in the S3 bucket.

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
identifierstringAn 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)
stream_session_identifierstringAn Amazon Resource Name (ARN) or ID that uniquely identifies the stream session resource. Example ARN: arn:aws:gameliftstreams:us-west-2:111122223333:streamsession/sg-1AB2C3De4/ABC123def4567. Example ID: ABC123def4567.
ExportFilesStatusstringFilter by the exported files status. You can specify one status in each request to retrieve only sessions that currently have that exported files status. Exported files can be in one of the following states: SUCCEEDED: The exported files are successfully stored in an S3 bucket. FAILED: The session ended but Amazon GameLift Streams couldn't collect and upload the files to S3. PENDING: Either the stream session is still in progress, or uploading the exported files to the S3 bucket is in progress.
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.
StatusstringFilter by the stream session status. You can specify one status in each request to retrieve only sessions that are currently in that status.

SELECT examples​

Retrieves properties for a Amazon GameLift Streams stream session resource. Specify the Amazon Resource Name (ARN) of the stream session that you want to retrieve and its stream group ARN. If the operation is successful, it returns properties for the requested resource.

SELECT
additional_environment_variables,
additional_launch_args,
application_arn,
arn,
connection_timeout_seconds,
created_at,
description,
display_configuration,
export_files_metadata,
last_updated_at,
location,
log_file_location_uri,
performance_stats_configuration,
protocol,
role_arn,
session_length_seconds,
signal_request,
signal_response,
status,
status_reason,
stream_group_id,
user_id,
web_sdk_protocol_url
FROM aws.gameliftstreams.stream_sessions
WHERE identifier = '{{ identifier }}' -- required
AND stream_session_identifier = '{{ stream_session_identifier }}' -- required
AND region = '{{ region }}' -- required
;

INSERT examples​

Enables clients to reconnect to a stream session while preserving all session state and data in the disconnected session. This reconnection process can be initiated when a stream session is in either PENDING_CLIENT_RECONNECTION or ACTIVE status. The process works as follows: Initial disconnect: When a client disconnects or loses connection, the stream session transitions from CONNECTED to PENDING_CLIENT_RECONNECTION Reconnection time window: Clients have ConnectionTimeoutSeconds (defined in StartStreamSession) to reconnect before session termination Your backend server must call CreateStreamSessionConnection to initiate reconnection Session transitions to RECONNECTING status Reconnection completion: On successful CreateStreamSessionConnection, session status changes to ACTIVE Provide the new connection information to the requesting client Client must establish connection within ConnectionTimeoutSeconds 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. To begin re-connecting to an existing stream session, specify the stream group ID and stream session ID that you want to reconnect to, and the signal request to use with the stream.

INSERT INTO aws.gameliftstreams.stream_sessions (
ClientToken,
SignalRequest,
identifier,
stream_session_identifier,
region
)
SELECT 
'{{ ClientToken }}',
'{{ SignalRequest }}' /* required */,
'{{ identifier }}',
'{{ stream_session_identifier }}',
'{{ region }}'
RETURNING
signal_response
;

DELETE examples​

Permanently terminates an active stream session. When called, the stream session status changes to TERMINATING. You can terminate a stream session in any status except ACTIVATING. If the stream session is in ACTIVATING status, an exception is thrown.

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

Lifecycle Methods​

Export the files that your application modifies or generates in a stream session, which can help you debug or verify your application. When your application runs, it generates output files such as logs, diagnostic information, crash dumps, save files, user data, screenshots, and so on. The files can be defined by the engine or frameworks that your application uses, or information that you've programmed your application to output. You can only call this action on a stream session that is in progress, specifically in one of the following statuses ACTIVE, CONNECTED, PENDING_CLIENT_RECONNECTION, and RECONNECTING. You must provide an Amazon Simple Storage Service (Amazon S3) bucket to store the files in. When the session ends, Amazon GameLift Streams produces a compressed folder that contains all of the files and directories that were modified or created by the application during the stream session. AWS uses your security credentials to authenticate and authorize access to your Amazon S3 bucket. Amazon GameLift Streams collects the following generated and modified files. Find them in the corresponding folders in the .zip archive. application/: The folder where your application or game is stored. profile/: The user profile folder. temp/: The system temp folder. To verify the status of the exported files, use GetStreamSession. To delete the files, delete the object in the S3 bucket.

EXEC aws.gameliftstreams.stream_sessions.export_stream_session_files 
@identifier='{{ identifier }}' --required, 
@stream_session_identifier='{{ stream_session_identifier }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"OutputUri": "{{ OutputUri }}"
}'
;
Last updated on