describePlayerSessions method

This API works with the following fleet types: EC2, Anywhere, Container

Retrieves properties for one or more player sessions.

This action can be used in the following ways:

• To retrieve a specific player session, provide the player session ID only.
• To retrieve all player sessions in a game session, provide the game session ID only.
• To retrieve all player sessions for a specific player, provide a player ID only.

To request player sessions, specify either a player session ID, game session ID, or player ID. You can filter this request by player session status. If you provide a specific PlayerSessionId or PlayerId, Amazon GameLift Servers ignores the filter criteria. Use the pagination parameters to retrieve results as a set of sequential pages.

If successful, a PlayerSession object is returned for each session that matches the request.

Related actions

All APIs by task

May throw InternalServiceException. May throw InvalidRequestException. May throw NotFoundException. May throw UnauthorizedException.

Parameter gameSessionId : An identifier for the game session that is unique across all regions to retrieve player sessions for. The value is always a full ARN in the following format: For Home Region game session - arn:aws:gamelift:<home_region>::gamesession/. For Remote Location game session - arn:aws:gamelift:<home_region>::gamesession/.

Parameter limit : The maximum number of results to return. Use this parameter with NextToken to get results as a set of sequential pages. If a player session ID is specified, this parameter is ignored.

Parameter nextToken : A token that indicates the start of the next sequential page of results. Use the token that is returned with a previous call to this operation. To start at the beginning of the result set, do not specify a value. If a player session ID is specified, this parameter is ignored.

Parameter playerId : A unique identifier for a player to retrieve player sessions for.

Parameter playerSessionId : A unique identifier for a player session to retrieve.

Parameter playerSessionStatusFilter : Player session status to filter results on. Note that when a PlayerSessionId or PlayerId is provided in a DescribePlayerSessions request, then the PlayerSessionStatusFilter has no effect on the response.

Possible player session statuses include the following:

• RESERVED -- The player session request has been received, but the player has not yet connected to the server process and/or been validated.
• ACTIVE -- The player has been validated by the server process and is currently connected.
• COMPLETED -- The player connection has been dropped.
• TIMEDOUT -- A player session request was received, but the player did not connect and/or was not validated within the timeout limit (60 seconds).

Future<DescribePlayerSessionsOutput> describePlayerSessions({
  String? gameSessionId,
  int? limit,
  String? nextToken,
  String? playerId,
  String? playerSessionId,
  String? playerSessionStatusFilter,
}) async {
  _s.validateNumRange(
    'limit',
    limit,
    1,
    1152921504606846976,
  );
  final headers = <String, String>{
    'Content-Type': 'application/x-amz-json-1.1',
    'X-Amz-Target': 'GameLift.DescribePlayerSessions'
  };
  final jsonResponse = await _protocol.send(
    method: 'POST',
    requestUri: '/',
    exceptionFnMap: _exceptionFns,
    // TODO queryParams
    headers: headers,
    payload: {
      if (gameSessionId != null) 'GameSessionId': gameSessionId,
      if (limit != null) 'Limit': limit,
      if (nextToken != null) 'NextToken': nextToken,
      if (playerId != null) 'PlayerId': playerId,
      if (playerSessionId != null) 'PlayerSessionId': playerSessionId,
      if (playerSessionStatusFilter != null)
        'PlayerSessionStatusFilter': playerSessionStatusFilter,
    },
  );

  return DescribePlayerSessionsOutput.fromJson(jsonResponse.body);
}