participants

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

Overview

Name	participants
Type	Resource
Id	aws.ivs_realtime.participants

Fields

The following fields are returned by SELECT queries:

get_participant

Name	Datatype	Description
attributes	object	Application-provided attributes to encode into the token and attach to a stage. Map keys and values can contain UTF-8 encoded text. The maximum length of this field is 1 KB total. This field is exposed to all stage participants and should not be used for personally identifying, confidential, or sensitive information.
browser_name	string	The participant’s browser. (pattern: <code>[a-zA-Z0-9-_.,:;\s]*</code>)
browser_version	string	The participant’s browser version. (pattern: <code>[a-zA-Z0-9-_.,:;\s]*</code>)
first_join_time	string (date-time)	ISO 8601 timestamp (returned as a string) when the participant first joined the stage session.
ingest_configuration_arn	string	The participant’s ingest configuration. (pattern: <code>arn:aws:ivs:[a-z0-9-]+:[0-9]+:ingest-configuration/[a-zA-Z0-9-]+</code>)
isp_name	string	The participant’s Internet Service Provider. (pattern: <code>[a-zA-Z0-9-_.,:;\s]*</code>)
os_name	string	The participant’s operating system. (pattern: <code>[a-zA-Z0-9-_.,:;\s]*</code>)
os_version	string	The participant’s operating system version. (pattern: <code>[a-zA-Z0-9-_.,:;\s]*</code>)
participant_id	string	Unique identifier for this participant, assigned by IVS. (pattern: <code>[a-zA-Z0-9-]*</code>)
protocol	string	Type of ingest protocol that the participant employs for broadcasting. (UNKNOWN, WHIP, RTMP, RTMPS)
published	boolean	Whether the participant ever published to the stage session.
recording_s3_bucket_name	string	Name of the S3 bucket to where the participant is being recorded, if individual participant recording is enabled, or "" (empty string), if recording is not enabled. (pattern: <code>[a-z0-9-.]*</code>)
recording_s3_prefix	string	S3 prefix of the S3 bucket where the participant is being recorded, if individual participant recording is enabled, or "" (empty string), if recording is not enabled. If individual participant recording merge is enabled, and if a stage publisher disconnects from a stage and then reconnects, IVS tries to record to the same S3 prefix as the previous session. See Merge Fragmented Individual Participant Recordings. (pattern: <code>[a-zA-Z0-9-]*</code>)
recording_state	string	The participant’s recording state. (STARTING, ACTIVE, STOPPING, STOPPED, FAILED, DISABLED)
redundant_ingest	boolean	Indicates whether redundant ingest is enabled for the participant.
replication_state	string	The participant's replication state. (ACTIVE, STOPPED)
replication_type	string	Indicates if the participant has been replicated to another stage or is a replica from another stage. Default: NONE. (SOURCE, REPLICA, NONE)
sdk_version	string	The participant’s SDK version. (pattern: <code>[a-zA-Z0-9-_.,:;\s]*</code>)
source_session_id	string	ID of the session within the source stage, if replicationType is REPLICA. (pattern: <code>st-[a-zA-Z0-9]+</code>)
source_stage_arn	string	Source stage ARN from which this participant is replicated, if replicationType is REPLICA. (pattern: <code>arn:aws:ivs:[a-z0-9-]+:[0-9]+:stage/[a-zA-Z0-9-]+</code>)
state	string	Whether the participant is connected to or disconnected from the stage. (CONNECTED, DISCONNECTED)
user_id	string	Customer-assigned name to help identify the token; this can be used to link a participant to a user in the customer’s own systems. This can be any UTF-8 encoded text. This field is exposed to all stage participants and should not be used for personally identifying, confidential, or sensitive information.

list_participants

Name	Datatype	Description
next_token	string	If there are more participants than maxResults, use nextToken in the request to get the next set. (pattern: <code>[a-zA-Z0-9+/=_-]*</code>)
participants	array	List of the matching participants (summary information only).

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_participant	select	region		Gets information about the specified participant token.
list_participants	select	region		Lists all participants in a specified stage session.
create_participant_token	insert	region, stageArn		Creates an additional token for a specified stage. This can be done after stage creation or when tokens expire. Tokens always are scoped to the stage for which they are created. Encryption keys are owned by Amazon IVS and never used directly by your application.
disconnect_participant	exec	region, stageArn, participantId		Disconnects a specified participant from a specified stage. If the participant is publishing using an IngestConfiguration, DisconnectParticipant also updates the stageArn in the IngestConfiguration to be an empty string.
start_participant_replication	exec	region, sourceStageArn, destinationStageArn, participantId		Starts replicating a publishing participant from a source stage to a destination stage.
stop_participant_replication	exec	region, sourceStageArn, destinationStageArn, participantId		Stops a replicated participant session.

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
region	string	AWS region (default: us-east-1)

SELECT examples

get_participant

Gets information about the specified participant token.

SELECT
attributes,
browser_name,
browser_version,
first_join_time,
ingest_configuration_arn,
isp_name,
os_name,
os_version,
participant_id,
protocol,
published,
recording_s3_bucket_name,
recording_s3_prefix,
recording_state,
redundant_ingest,
replication_state,
replication_type,
sdk_version,
source_session_id,
source_stage_arn,
state,
user_id
FROM aws.ivs_realtime.participants
WHERE region = '{{ region }}' -- required
;

list_participants

Lists all participants in a specified stage session.

SELECT
next_token,
participants
FROM aws.ivs_realtime.participants
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_participant_token

Creates an additional token for a specified stage. This can be done after stage creation or when tokens expire. Tokens always are scoped to the stage for which they are created. Encryption keys are owned by Amazon IVS and never used directly by your application.

INSERT INTO aws.ivs_realtime.participants (
stageArn,
duration,
userId,
attributes,
capabilities,
region
)
SELECT 
'{{ stageArn }}' /* required */,
{{ duration }},
'{{ userId }}',
'{{ attributes }}',
'{{ capabilities }}',
'{{ region }}'
RETURNING
participant_token
;

Manifest

# Description fields are for documentation purposes
- name: participants
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the participants resource.
  - name: stageArn
    value: "{{ stageArn }}"
  - name: duration
    value: {{ duration }}
  - name: userId
    value: "{{ userId }}"
  - name: attributes
    value: "{{ attributes }}"
  - name: capabilities
    value:
      - "{{ capabilities }}"

Lifecycle Methods

disconnect_participant

Disconnects a specified participant from a specified stage. If the participant is publishing using an IngestConfiguration, DisconnectParticipant also updates the stageArn in the IngestConfiguration to be an empty string.

EXEC aws.ivs_realtime.participants.disconnect_participant 
@region='{{ region }}' --required 
@@json=
'{
"stageArn": "{{ stageArn }}", 
"participantId": "{{ participantId }}", 
"reason": "{{ reason }}"
}'
;

start_participant_replication

Starts replicating a publishing participant from a source stage to a destination stage.

EXEC aws.ivs_realtime.participants.start_participant_replication 
@region='{{ region }}' --required 
@@json=
'{
"sourceStageArn": "{{ sourceStageArn }}", 
"destinationStageArn": "{{ destinationStageArn }}", 
"participantId": "{{ participantId }}", 
"reconnectWindowSeconds": {{ reconnectWindowSeconds }}, 
"attributes": "{{ attributes }}"
}'
;

stop_participant_replication

Stops a replicated participant session.

EXEC aws.ivs_realtime.participants.stop_participant_replication 
@region='{{ region }}' --required 
@@json=
'{
"sourceStageArn": "{{ sourceStageArn }}", 
"destinationStageArn": "{{ destinationStageArn }}", 
"participantId": "{{ participantId }}"
}'
;