stream_urls

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

Overview

Name	stream_urls
Type	Resource
Id	aws.gameliftstreams.stream_urls

Fields

The following fields are returned by SELECT queries:

get_stream_url

Name	Datatype	Description
additional_environment_variables	object	The environment variables made available to the application when a stream session starts.
additional_launch_args	array	The command-line arguments passed to the application when a stream session starts.
application_arn	string	The application that runs in the stream sessions. 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>)
arn	string	The Amazon Resource Name (ARN) that uniquely identifies the stream URL across all Amazon Web Services Regions. Format is arn:aws:gameliftstreams:[AWS Region]:[AWS account]:streamurl/[stream group resource ID]/[stream URL resource ID]. (pattern: <code>arn:aws:gameliftstreams:([^: ]):([0-9]{12}):([^: ])</code>)
created_at	string (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).
description	string	The descriptive label for the stream URL. (pattern: <code>[a-zA-Z0-9-.!+@/][a-zA-Z0-9-.!+@/ ]*</code>)
display_configuration	object	The virtual monitor settings for a stream session, including the resolution. If not specified, the stream session uses the default resolution of 1920 × 1080.
expires_at	string (date-time)	The date and time when the stream URL expires and stops accepting new stream sessions. Timestamps are expressed using in ISO8601 format, such as: 2022-12-27T22:29:40+00:00 (UTC).
locations	array	The list of locations, in order of preference, where Amazon GameLift Streams places the stream session. For a complete list of locations that Amazon GameLift Streams supports, refer to Regions, quotas, and limitations in the Amazon GameLift Streams Developer Guide.
protocol	string	The data transport protocol used for stream sessions started from this stream URL. (WebRTC)
remaining_uses	integer	The number of times the stream URL can still be used to start a stream session.
role_arn	string	The Amazon Resource Name (ARN) of the IAM role that Amazon GameLift Streams assumes during stream sessions started from this stream URL. For more information, see Provide AWS credentials to your streaming application in the Amazon GameLift Streams Developer Guide. (pattern: <code>arn:aws[a-zA-Z-]*:iam::\d{12}:role/.+</code>)
session_length_seconds	integer	The maximum length of time, in seconds, that a stream session started from this stream URL can run.
status	string	The current status of the stream URL. Possible statuses include the following: ACTIVE: The stream URL is valid and can start stream sessions. EXPIRED: The stream URL has passed its expiration time and can no longer start stream sessions. REVOKED: The stream URL was revoked and can no longer start stream sessions. LIMIT_REACHED: The stream URL has been used the maximum number of times and can no longer start stream sessions. (ACTIVE, EXPIRED, REVOKED, LIMIT_REACHED)
status_reason	string	Additional information about why the stream URL is in its current status. Amazon GameLift Streams populates this value when the status is REVOKED. Possible values include the following: userRevoked: You revoked the stream URL. revokedAndTerminatingSessions: You revoked the stream URL and Amazon GameLift Streams is ending its running stream sessions. revokedAndSessionsTerminated: You revoked the stream URL and its running stream sessions have ended. streamGroupDeleted: The stream group was deleted, which revoked the stream URL. applicationDeleted: The application was deleted, which revoked the stream URL. (userRevoked, revokedAndTerminatingSessions, revokedAndSessionsTerminated, streamGroupDeleted, applicationDeleted)
stream_group_arn	string	The stream group that runs the stream sessions. This value is an Amazon Resource Name (ARN) that uniquely identifies the stream group resource. Example ARN: arn:aws:gameliftstreams:us-west-2:111122223333:streamgroup/sg-1AB2C3De4. (pattern: <code>arn:aws:gameliftstreams:([^: ]):([0-9]{12}):([^: ])</code>)
stream_sessions	array	A list of the stream sessions that have been started through this stream URL.
stream_url	string	The shareable stream URL. Distribute this URL to end users so that they can start and play a stream session in a hosted web player. Treat the stream URL as a secret. Anyone who has it can start a stream session until the stream URL expires, is revoked, or reaches its usage limit.
stream_url_id	string	The unique identifier for the stream URL resource, for example su-1AB2C3De4. (pattern: <code>[a-zA-Z0-9-]+</code>)
usage_limit	integer	The maximum number of times the stream URL can start a stream session.

list_stream_urls

Name	Datatype	Description
application_arn	string	The application that runs in the stream sessions. 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>)
arn	string	The Amazon Resource Name (ARN) that uniquely identifies the stream URL across all Amazon Web Services Regions. Format is arn:aws:gameliftstreams:[AWS Region]:[AWS account]:streamurl/[stream group resource ID]/[stream URL resource ID]. (pattern: <code>arn:aws:gameliftstreams:([^: ]):([0-9]{12}):([^: ])</code>)
created_at	string (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).
description	string	The descriptive label for the stream URL. (pattern: <code>[a-zA-Z0-9-.!+@/][a-zA-Z0-9-.!+@/ ]*</code>)
expires_at	string (date-time)	The date and time when the stream URL expires and stops accepting new stream sessions. Timestamps are expressed using in ISO8601 format, such as: 2022-12-27T22:29:40+00:00 (UTC).
remaining_uses	integer	The number of times the stream URL can still be used to start a stream session.
session_length_seconds	integer	The maximum length of time, in seconds, that a stream session started from this stream URL can run.
status	string	The current status of the stream URL. Possible statuses include the following: ACTIVE: The stream URL is valid and can start stream sessions. EXPIRED: The stream URL has passed its expiration time and can no longer start stream sessions. REVOKED: The stream URL was revoked and can no longer start stream sessions. LIMIT_REACHED: The stream URL has been used the maximum number of times and can no longer start stream sessions. (ACTIVE, EXPIRED, REVOKED, LIMIT_REACHED)
status_reason	string	Additional information about why the stream URL is in its current status. Amazon GameLift Streams populates this value when the status is REVOKED. Possible values include the following: userRevoked: You revoked the stream URL. revokedAndTerminatingSessions: You revoked the stream URL and Amazon GameLift Streams is ending its running stream sessions. revokedAndSessionsTerminated: You revoked the stream URL and its running stream sessions have ended. streamGroupDeleted: The stream group was deleted, which revoked the stream URL. applicationDeleted: The application was deleted, which revoked the stream URL. (userRevoked, revokedAndTerminatingSessions, revokedAndSessionsTerminated, streamGroupDeleted, applicationDeleted)
stream_group_arn	string	The stream group that runs the stream sessions. This value is an Amazon Resource Name (ARN) that uniquely identifies the stream group resource. Example ARN: arn:aws:gameliftstreams:us-west-2:111122223333:streamgroup/sg-1AB2C3De4. (pattern: <code>arn:aws:gameliftstreams:([^: ]):([0-9]{12}):([^: ])</code>)
stream_url	string	The shareable stream URL. Distribute this URL to end users so that they can start and play a stream session in a hosted web player. Treat the stream URL as a secret. Anyone who has it can start a stream session until the stream URL expires, is revoked, or reaches its usage limit.
stream_url_id	string	The unique identifier for the stream URL resource, for example su-1AB2C3De4. (pattern: <code>[a-zA-Z0-9-]+</code>)
usage_limit	integer	The maximum number of times the stream URL can start a stream session.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_stream_url	select	identifier, stream_url_identifier, region		Retrieves properties for a stream URL, including its current status, usage, and the stream sessions started through it. If you delete the stream group or application that backs the stream URL, this operation updates the status of the stream URL to REVOKED.
list_stream_urls	select	region	Status, StreamGroupIdentifier, NextToken, MaxResults	Retrieves a list of the stream URLs in the current Amazon Web Services Region for your Amazon Web Services account. You can filter the results by status or by stream group. Use the pagination parameters to retrieve results as a set of sequential pages. If you delete the stream group or application that backs a stream URL, this operation updates that stream URL's status to REVOKED.
create_stream_url	insert	identifier, region, ApplicationIdentifier, UrlExpiresAfterMinutes		Creates a stream URL that grants temporary access to a stream session in a web browser without requiring an Amazon Web Services account or client integration. You can use the stream URL to start a stream session up to the number of times set by UsageLimit, until it expires after UrlExpiresAfterMinutes. Each successful use starts a new stream session. To make the request idempotent, provide a ClientToken.
revoke_stream_url	update	identifier, stream_url_identifier, region		Revokes a stream URL so that it can no longer start new stream sessions. By default, stream sessions that are already running continue until they end on their own. To also end running sessions, set RevocationMode to REVOKE_AND_TERMINATE_SESSIONS. Revoking a stream URL is permanent. The status of the stream URL changes to REVOKED.

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.

Name	Datatype	Description
identifier	string	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. This is the stream group that owns the stream URL.
region	string	AWS region (default: us-east-1)
stream_url_identifier	string	The unique identifier of the stream URL to revoke. Specify a stream URL ID or Amazon Resource Name (ARN). Example ARN: arn:aws:gameliftstreams:us-west-2:111122223333:streamurl/sg-1AB2C3De4/su-1AB2C3De4. Example ID: su-1AB2C3De4.
MaxResults	integer	The maximum number of results to return per page. Valid values are 1-100. The default is 25.
NextToken	string	The 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.
Status	string	Filters the list to stream URLs with the specified status. ACTIVE: The stream URL is valid and can start stream sessions. EXPIRED: The stream URL has passed its expiration time and can no longer start stream sessions. REVOKED: The stream URL was revoked and can no longer start stream sessions. LIMIT_REACHED: The stream URL has been used the maximum number of times and can no longer start stream sessions.
StreamGroupIdentifier	string	Filters the list to stream URLs that belong to the specified stream group. 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.

SELECT examples

get_stream_url

Retrieves properties for a stream URL, including its current status, usage, and the stream sessions started through it. If you delete the stream group or application that backs the stream URL, this operation updates the status of the stream URL to REVOKED.

SELECT
additional_environment_variables,
additional_launch_args,
application_arn,
arn,
created_at,
description,
display_configuration,
expires_at,
locations,
protocol,
remaining_uses,
role_arn,
session_length_seconds,
status,
status_reason,
stream_group_arn,
stream_sessions,
stream_url,
stream_url_id,
usage_limit
FROM aws.gameliftstreams.stream_urls
WHERE identifier = '{{ identifier }}' -- required
AND stream_url_identifier = '{{ stream_url_identifier }}' -- required
AND region = '{{ region }}' -- required
;

list_stream_urls

Retrieves a list of the stream URLs in the current Amazon Web Services Region for your Amazon Web Services account. You can filter the results by status or by stream group. Use the pagination parameters to retrieve results as a set of sequential pages. If you delete the stream group or application that backs a stream URL, this operation updates that stream URL's status to REVOKED.

SELECT
application_arn,
arn,
created_at,
description,
expires_at,
remaining_uses,
session_length_seconds,
status,
status_reason,
stream_group_arn,
stream_url,
stream_url_id,
usage_limit
FROM aws.gameliftstreams.stream_urls
WHERE region = '{{ region }}' -- required
AND Status = '{{ Status }}'
AND StreamGroupIdentifier = '{{ StreamGroupIdentifier }}'
AND NextToken = '{{ NextToken }}'
AND MaxResults = '{{ MaxResults }}'
;

INSERT examples

create_stream_url

Creates a stream URL that grants temporary access to a stream session in a web browser without requiring an Amazon Web Services account or client integration. You can use the stream URL to start a stream session up to the number of times set by UsageLimit, until it expires after UrlExpiresAfterMinutes. Each successful use starts a new stream session. To make the request idempotent, provide a ClientToken.

INSERT INTO aws.gameliftstreams.stream_urls (
ApplicationIdentifier,
Protocol,
UrlExpiresAfterMinutes,
UsageLimit,
Description,
Locations,
SessionLengthSeconds,
AdditionalLaunchArgs,
AdditionalEnvironmentVariables,
RoleArn,
DisplayConfiguration,
ClientToken,
identifier,
region
)
SELECT 
'{{ ApplicationIdentifier }}' /* required */,
'{{ Protocol }}',
{{ UrlExpiresAfterMinutes }} /* required */,
{{ UsageLimit }},
'{{ Description }}',
'{{ Locations }}',
{{ SessionLengthSeconds }},
'{{ AdditionalLaunchArgs }}',
'{{ AdditionalEnvironmentVariables }}',
'{{ RoleArn }}',
'{{ DisplayConfiguration }}',
'{{ ClientToken }}',
'{{ identifier }}',
'{{ region }}'
RETURNING
additional_environment_variables,
additional_launch_args,
application_arn,
arn,
created_at,
description,
display_configuration,
expires_at,
locations,
protocol,
remaining_uses,
role_arn,
session_length_seconds,
status,
status_reason,
stream_group_arn,
stream_url,
stream_url_id,
usage_limit
;

Manifest

# Description fields are for documentation purposes
- name: stream_urls
props:
  - name: identifier
    value: "{{ identifier }}"
    description: Required parameter for the stream_urls resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the stream_urls resource.
  - name: ApplicationIdentifier
    value: "{{ ApplicationIdentifier }}"
  - name: Protocol
    value: "{{ Protocol }}"
    valid_values: ['WebRTC']
  - name: UrlExpiresAfterMinutes
    value: {{ UrlExpiresAfterMinutes }}
  - name: UsageLimit
    value: {{ UsageLimit }}
  - name: Description
    value: "{{ Description }}"
  - name: Locations
    value:
      - "{{ Locations }}"
  - name: SessionLengthSeconds
    value: {{ SessionLengthSeconds }}
  - name: AdditionalLaunchArgs
    value:
      - "{{ AdditionalLaunchArgs }}"
  - name: AdditionalEnvironmentVariables
    value: "{{ AdditionalEnvironmentVariables }}"
  - name: RoleArn
    value: "{{ RoleArn }}"
  - name: DisplayConfiguration
    description: |
      The virtual monitor settings for a stream session, including the resolution. If not specified, the stream session uses the default resolution of 1920 × 1080.
    value:
      Resolution:
        Width: {{ Width }}
        Height: {{ Height }}
  - name: ClientToken
    value: "{{ ClientToken }}"

UPDATE examples

revoke_stream_url

Revokes a stream URL so that it can no longer start new stream sessions. By default, stream sessions that are already running continue until they end on their own. To also end running sessions, set RevocationMode to REVOKE_AND_TERMINATE_SESSIONS. Revoking a stream URL is permanent. The status of the stream URL changes to REVOKED.

UPDATE aws.gameliftstreams.stream_urls
SET 
RevocationMode = '{{ RevocationMode }}'
WHERE 
identifier = '{{ identifier }}' --required
AND stream_url_identifier = '{{ stream_url_identifier }}' --required
AND region = '{{ region }}' --required;