aws_sdk_gameliftstreams/client/

start_stream_session.rs

// Code generated by software.amazon.smithy.rust.codegen.smithy-rs. DO NOT EDIT.
impl super::Client {
    /// Constructs a fluent builder for the [`StartStreamSession`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder) operation.
    ///
    /// - The fluent builder is configurable:
    ///   - [`client_token(impl Into<String>)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::client_token) / [`set_client_token(Option<String>)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::set_client_token):<br>required: **false**<br><p>A unique identifier that represents a client request. The request is idempotent, which ensures that an API request completes only once. When users send a request, Amazon GameLift Streams automatically populates this field.</p><br>
    ///   - [`description(impl Into<String>)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::description) / [`set_description(Option<String>)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::set_description):<br>required: **false**<br><p>A human-readable label for the stream session. You can update this value later.</p><br>
    ///   - [`identifier(impl Into<String>)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::identifier) / [`set_identifier(Option<String>)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::set_identifier):<br>required: **true**<br><p>The stream group to run this stream session with.</p> <p>This value is an <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html">Amazon Resource Name (ARN)</a> or ID that uniquely identifies the stream group resource. Example ARN: <code>arn:aws:gameliftstreams:us-west-2:111122223333:streamgroup/sg-1AB2C3De4</code>. Example ID: <code>sg-1AB2C3De4</code>.</p><br>
    ///   - [`protocol(Protocol)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::protocol) / [`set_protocol(Option<Protocol>)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::set_protocol):<br>required: **true**<br><p>The data transport protocol to use for the stream session.</p><br>
    ///   - [`signal_request(impl Into<String>)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::signal_request) / [`set_signal_request(Option<String>)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::set_signal_request):<br>required: **true**<br><p>A WebRTC ICE offer string to use when initializing a WebRTC connection. Typically, the offer is a very long JSON string. Provide the string as a text value in quotes.</p> <p>Amazon GameLift Streams also supports setting the field to "NO_CLIENT_CONNECTION". This will create a session without needing any browser request or Web SDK integration. The session starts up as usual and waits for a reconnection from a browser, which is accomplished using <a href="https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_CreateStreamSessionConnection.html">CreateStreamSessionConnection</a>.</p><br>
    ///   - [`application_identifier(impl Into<String>)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::application_identifier) / [`set_application_identifier(Option<String>)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::set_application_identifier):<br>required: **true**<br><p>An <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html">Amazon Resource Name (ARN)</a> or ID that uniquely identifies the application resource. Example ARN: <code>arn:aws:gameliftstreams:us-west-2:111122223333:application/a-9ZY8X7Wv6</code>. Example ID: <code>a-9ZY8X7Wv6</code>.</p><br>
    ///   - [`user_id(impl Into<String>)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::user_id) / [`set_user_id(Option<String>)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::set_user_id):<br>required: **false**<br><p>An opaque, unique identifier for an end-user, defined by the developer.</p><br>
    ///   - [`locations(impl Into<String>)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::locations) / [`set_locations(Option<Vec::<String>>)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::set_locations):<br>required: **false**<br><p>A list of locations, in order of priority, where you want Amazon GameLift Streams to start a stream from. For example, <code>us-east-1</code>. Amazon GameLift Streams selects the location with the next available capacity to start a single stream session in. If this value is empty, Amazon GameLift Streams attempts to start a stream session in the primary location.</p> <p>For a complete list of locations that Amazon GameLift Streams supports, refer to <a href="https://docs.aws.amazon.com/gameliftstreams/latest/developerguide/regions-quotas.html">Regions, quotas, and limitations</a> in the <i>Amazon GameLift Streams Developer Guide</i>.</p><br>
    ///   - [`connection_timeout_seconds(i32)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::connection_timeout_seconds) / [`set_connection_timeout_seconds(Option<i32>)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::set_connection_timeout_seconds):<br>required: **false**<br><p>Length of time (in seconds) that Amazon GameLift Streams should wait for a client to connect or reconnect to the stream session. Applies to both connection and reconnection scenarios. This time span starts when the stream session reaches <code>ACTIVE</code> state. If no client connects before the timeout, Amazon GameLift Streams terminates the stream session. Default value is 120.</p><br>
    ///   - [`session_length_seconds(i32)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::session_length_seconds) / [`set_session_length_seconds(Option<i32>)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::set_session_length_seconds):<br>required: **false**<br><p>The 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. Default value is 43200 (12 hours).</p><br>
    ///   - [`additional_launch_args(impl Into<String>)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::additional_launch_args) / [`set_additional_launch_args(Option<Vec::<String>>)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::set_additional_launch_args):<br>required: **false**<br><p>A 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.</p> <p><code>AdditionalEnvironmentVariables</code> and <code>AdditionalLaunchArgs</code> have similar purposes. <code>AdditionalEnvironmentVariables</code> passes data using environment variables; while <code>AdditionalLaunchArgs</code> passes data using command-line arguments.</p><br>
    ///   - [`additional_environment_variables(impl Into<String>, impl Into<String>)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::additional_environment_variables) / [`set_additional_environment_variables(Option<HashMap::<String, String>>)`](crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::set_additional_environment_variables):<br>required: **false**<br><p>A 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.</p><note>  <p>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.</p> </note> <p><code>AdditionalEnvironmentVariables</code> and <code>AdditionalLaunchArgs</code> have similar purposes. <code>AdditionalEnvironmentVariables</code> passes data using environment variables; while <code>AdditionalLaunchArgs</code> passes data using command-line arguments.</p><br>
    /// - On success, responds with [`StartStreamSessionOutput`](crate::operation::start_stream_session::StartStreamSessionOutput) with field(s):
    ///   - [`arn(Option<String>)`](crate::operation::start_stream_session::StartStreamSessionOutput::arn): <p>The <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html">Amazon Resource Name (ARN)</a> 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 <code>arn:aws:gameliftstreams:\[AWS Region\]:\[AWS account\]:streamsession/\[stream group resource ID\]/\[stream session resource ID\]</code>.</p>
    ///   - [`description(Option<String>)`](crate::operation::start_stream_session::StartStreamSessionOutput::description): <p>A human-readable label for the stream session. You can update this value at any time.</p>
    ///   - [`stream_group_id(Option<String>)`](crate::operation::start_stream_session::StartStreamSessionOutput::stream_group_id): <p>The unique identifier for the Amazon GameLift Streams stream group that is hosting the stream session. Format example: <code>sg-1AB2C3De4</code>.</p>
    ///   - [`user_id(Option<String>)`](crate::operation::start_stream_session::StartStreamSessionOutput::user_id): <p>An opaque, unique identifier for an end-user, defined by the developer.</p>
    ///   - [`status(Option<StreamSessionStatus>)`](crate::operation::start_stream_session::StartStreamSessionOutput::status): <p>The current status of the stream session. A stream session is ready for a client to connect when in <code>ACTIVE</code> status.</p> <ul>  <li>   <p><code>ACTIVATING</code>: The stream session is starting and preparing to stream.</p></li>  <li>   <p><code>ACTIVE</code>: The stream session is ready and waiting for a client connection. A client has <code>ConnectionTimeoutSeconds</code> (specified in <code>StartStreamSession</code>) from when the session reaches <code>ACTIVE</code> state to establish a connection. If no client connects within this timeframe, the session automatically terminates.</p></li>  <li>   <p><code>CONNECTED</code>: 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 <code>SessionLengthSeconds</code> in <code>StartStreamSession</code> is exceeded.</p></li>  <li>   <p><code>ERROR</code>: The stream session failed to activate. See <code>StatusReason</code> (returned by <code>GetStreamSession</code> and <code>StartStreamSession</code>) for more information.</p></li>  <li>   <p><code>PENDING_CLIENT_RECONNECTION</code>: A client has recently disconnected and the stream session is waiting for the client to reconnect. A client has <code>ConnectionTimeoutSeconds</code> (specified in <code>StartStreamSession</code>) from when the session reaches <code>PENDING_CLIENT_RECONNECTION</code> state to re-establish a connection. If no client connects within this timeframe, the session automatically terminates.</p></li>  <li>   <p><code>RECONNECTING</code>: A client has initiated a reconnect to a session that was in <code>PENDING_CLIENT_RECONNECTION</code> state.</p></li>  <li>   <p><code>TERMINATING</code>: The stream session is ending.</p></li>  <li>   <p><code>TERMINATED</code>: The stream session has ended.</p></li> </ul>
    ///   - [`status_reason(Option<StreamSessionStatusReason>)`](crate::operation::start_stream_session::StartStreamSessionOutput::status_reason): <p>A short description of the reason the stream session is in <code>ERROR</code> status or <code>TERMINATED</code> status.</p> <p><code>ERROR</code> status reasons:</p> <ul>  <li>   <p><code>applicationLogS3DestinationError</code>: Could not write the application log to the Amazon S3 bucket that is configured for the streaming application. Make sure the bucket still exists.</p></li>  <li>   <p><code>internalError</code>: An internal service error occurred. Start a new stream session to continue streaming.</p></li>  <li>   <p><code>invalidSignalRequest</code>: The WebRTC signal request that was sent is not valid. When starting or reconnecting to a stream session, use <code>generateSignalRequest</code> in the Amazon GameLift Streams Web SDK to generate a new signal request.</p></li>  <li>   <p><code>placementTimeout</code>: 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.</p></li> </ul> <p><code>TERMINATED</code> status reasons:</p> <ul>  <li>   <p><code>apiTerminated</code>: The stream session was terminated by an API call to <a href="https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_TerminateStreamSession.html">TerminateStreamSession</a>.</p></li>  <li>   <p><code>applicationExit</code>: The streaming application exited or crashed. The stream session was terminated because the application is no longer running.</p></li>  <li>   <p><code>connectionTimeout</code>: The stream session was terminated because the client failed to connect within the connection timeout period specified by <code>ConnectionTimeoutSeconds</code>.</p></li>  <li>   <p><code>idleTimeout</code>: The stream session was terminated because it exceeded the idle timeout period of 60 minutes with no user input activity.</p></li>  <li>   <p><code>maxSessionLengthTimeout</code>: The stream session was terminated because it exceeded the maximum session length timeout period specified by <code>SessionLengthSeconds</code>.</p></li>  <li>   <p><code>reconnectionTimeout</code>: The stream session was terminated because the client failed to reconnect within the reconnection timeout period specified by <code>ConnectionTimeoutSeconds</code> after losing connection.</p></li> </ul>
    ///   - [`protocol(Option<Protocol>)`](crate::operation::start_stream_session::StartStreamSessionOutput::protocol): <p>The data transfer protocol in use with the stream session.</p>
    ///   - [`location(Option<String>)`](crate::operation::start_stream_session::StartStreamSessionOutput::location): <p>The location where Amazon GameLift Streams hosts and streams your application. For example, <code>us-east-1</code>. For a complete list of locations that Amazon GameLift Streams supports, refer to <a href="https://docs.aws.amazon.com/gameliftstreams/latest/developerguide/regions-quotas.html">Regions, quotas, and limitations</a> in the <i>Amazon GameLift Streams Developer Guide</i>.</p>
    ///   - [`signal_request(Option<String>)`](crate::operation::start_stream_session::StartStreamSessionOutput::signal_request): <p>The WebRTC ICE offer string that a client generates to initiate a connection to the stream session.</p>
    ///   - [`signal_response(Option<String>)`](crate::operation::start_stream_session::StartStreamSessionOutput::signal_response): <p>The WebRTC answer string that the stream server generates in response to the <code>SignalRequest</code>.</p>
    ///   - [`connection_timeout_seconds(Option<i32>)`](crate::operation::start_stream_session::StartStreamSessionOutput::connection_timeout_seconds): <p>The 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 <code>ACTIVE</code> or <code>PENDING_CLIENT_RECONNECTION</code> state. If no client connects (or reconnects) before the timeout, Amazon GameLift Streams terminates the stream session.</p>
    ///   - [`session_length_seconds(Option<i32>)`](crate::operation::start_stream_session::StartStreamSessionOutput::session_length_seconds): <p>The 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.</p>
    ///   - [`additional_launch_args(Option<Vec::<String>>)`](crate::operation::start_stream_session::StartStreamSessionOutput::additional_launch_args): <p>A 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.</p> <p><code>AdditionalEnvironmentVariables</code> and <code>AdditionalLaunchArgs</code> have similar purposes. <code>AdditionalEnvironmentVariables</code> passes data using environment variables; while <code>AdditionalLaunchArgs</code> passes data using command-line arguments.</p>
    ///   - [`additional_environment_variables(Option<HashMap::<String, String>>)`](crate::operation::start_stream_session::StartStreamSessionOutput::additional_environment_variables): <p>A 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.</p><note>  <p>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.</p> </note> <p><code>AdditionalEnvironmentVariables</code> and <code>AdditionalLaunchArgs</code> have similar purposes. <code>AdditionalEnvironmentVariables</code> passes data using environment variables; while <code>AdditionalLaunchArgs</code> passes data using command-line arguments.</p>
    ///   - [`log_file_location_uri(Option<String>)`](crate::operation::start_stream_session::StartStreamSessionOutput::log_file_location_uri): <p>Access 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.</p>
    ///   - [`web_sdk_protocol_url(Option<String>)`](crate::operation::start_stream_session::StartStreamSessionOutput::web_sdk_protocol_url): <p>The URL of an S3 bucket that stores Amazon GameLift Streams WebSDK files. The URL is used to establish connection with the client.</p>
    ///   - [`last_updated_at(Option<DateTime>)`](crate::operation::start_stream_session::StartStreamSessionOutput::last_updated_at): <p>A timestamp that indicates when this resource was last updated. Timestamps are expressed using in ISO8601 format, such as: <code>2022-12-27T22:29:40+00:00</code> (UTC).</p>
    ///   - [`created_at(Option<DateTime>)`](crate::operation::start_stream_session::StartStreamSessionOutput::created_at): <p>A timestamp that indicates when this resource was created. Timestamps are expressed using in ISO8601 format, such as: <code>2022-12-27T22:29:40+00:00</code> (UTC).</p>
    ///   - [`application_arn(Option<String>)`](crate::operation::start_stream_session::StartStreamSessionOutput::application_arn): <p>The application streaming in this session.</p> <p>This value is an <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html">Amazon Resource Name (ARN)</a> that uniquely identifies the application resource. Example ARN: <code>arn:aws:gameliftstreams:us-west-2:111122223333:application/a-9ZY8X7Wv6</code>.</p>
    ///   - [`export_files_metadata(Option<ExportFilesMetadata>)`](crate::operation::start_stream_session::StartStreamSessionOutput::export_files_metadata): <p>Provides details about the stream session's exported files.</p>
    /// - On failure, responds with [`SdkError<StartStreamSessionError>`](crate::operation::start_stream_session::StartStreamSessionError)
    pub fn start_stream_session(&self) -> crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder {
        crate::operation::start_stream_session::builders::StartStreamSessionFluentBuilder::new(self.handle.clone())
    }
}