describePlayerSessions method

Future<DescribePlayerSessionsOutput> describePlayerSessions({
  1. String? gameSessionId,
  2. int? limit,
  3. String? nextToken,
  4. String? playerId,
  5. String? playerSessionId,
  6. String? playerSessionStatusFilter,
})

Retrieves properties for one or more player sessions. This operation can be used in several ways: (1) provide a PlayerSessionId to request properties for a specific player session; (2) provide a GameSessionId to request properties for all player sessions in the specified game session; (3) provide a PlayerId to request properties for all player sessions of a specified player.

To get game session record(s), specify only one of the following: a player session ID, a game session ID, or a player ID. You can filter this request by player session status. Use the pagination parameters to retrieve results as a set of sequential pages. If successful, a PlayerSession object is returned for each session matching the request.

Available in Amazon GameLift Local.

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

Parameter gameSessionId : A unique identifier for the game session to retrieve player sessions for.

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 : 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.

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).

Implementation

Future<DescribePlayerSessionsOutput> describePlayerSessions({
  String? gameSessionId,
  int? limit,
  String? nextToken,
  String? playerId,
  String? playerSessionId,
  String? playerSessionStatusFilter,
}) async {
  _s.validateStringLength(
    'gameSessionId',
    gameSessionId,
    1,
    256,
  );
  _s.validateNumRange(
    'limit',
    limit,
    1,
    1152921504606846976,
  );
  _s.validateStringLength(
    'nextToken',
    nextToken,
    1,
    1024,
  );
  _s.validateStringLength(
    'playerId',
    playerId,
    1,
    1024,
  );
  _s.validateStringLength(
    'playerSessionStatusFilter',
    playerSessionStatusFilter,
    1,
    1024,
  );
  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);
}