:doc:`GameLift <../../gamelift>` / Client / describe_player_sessions

************************
describe_player_sessions
************************



.. py:method:: GameLift.Client.describe_player_sessions(**kwargs)

  

  **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 <https://docs.aws.amazon.com/gamelift/latest/developerguide/reference-awssdk.html#reference-awssdk-resources-fleets>`__

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/gamelift-2015-10-01/DescribePlayerSessions>`_  


  **Request Syntax**
  ::

    response = client.describe_player_sessions(
        GameSessionId='string',
        PlayerId='string',
        PlayerSessionId='string',
        PlayerSessionStatusFilter='string',
        Limit=123,
        NextToken='string'
    )
    
  :type GameSessionId: string
  :param GameSessionId: 

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

    

  
  :type PlayerId: string
  :param PlayerId: 

    A unique identifier for a player to retrieve player sessions for.

    

  
  :type PlayerSessionId: string
  :param PlayerSessionId: 

    A unique identifier for a player session to retrieve.

    

  
  :type PlayerSessionStatusFilter: string
  :param 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).
    

    

  
  :type Limit: integer
  :param 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.

    

  
  :type NextToken: string
  :param 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.

    

  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'PlayerSessions': [
              {
                  'PlayerSessionId': 'string',
                  'PlayerId': 'string',
                  'GameSessionId': 'string',
                  'FleetId': 'string',
                  'FleetArn': 'string',
                  'CreationTime': datetime(2015, 1, 1),
                  'TerminationTime': datetime(2015, 1, 1),
                  'Status': 'RESERVED'|'ACTIVE'|'COMPLETED'|'TIMEDOUT',
                  'IpAddress': 'string',
                  'DnsName': 'string',
                  'Port': 123,
                  'PlayerData': 'string'
              },
          ],
          'NextToken': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **PlayerSessions** *(list) --* 

        A collection of objects containing properties for each player session that matches the request.

        
        

        - *(dict) --* 

          Represents a player session. Player sessions are created either for a specific game session, or as part of a game session placement or matchmaking request. A player session can represents a reserved player slot in a game session (when status is ``RESERVED``) or actual player activity in a game session (when status is ``ACTIVE``). A player session object, including player data, is automatically passed to a game session when the player connects to the game session and is validated. After the game session ends, player sessions information is retained for 30 days and then removed.

           

          **Related actions**

           

          `All APIs by task <https://docs.aws.amazon.com/gamelift/latest/developerguide/reference-awssdk.html#reference-awssdk-resources-fleets>`__

          
          

          - **PlayerSessionId** *(string) --* 

            A unique identifier for a player session.

            
          

          - **PlayerId** *(string) --* 

            A unique identifier for a player that is associated with this player session.

            
          

          - **GameSessionId** *(string) --* 

            A unique identifier for the game session that the player session is connected to.

            
          

          - **FleetId** *(string) --* 

            A unique identifier for the fleet that the player's game session is running on.

            
          

          - **FleetArn** *(string) --* 

            The Amazon Resource Name ( `ARN <https://docs.aws.amazon.com/AmazonS3/latest/dev/s3-arn-format.html>`__) associated with the GameLift fleet that the player's game session is running on.

            
          

          - **CreationTime** *(datetime) --* 

            A time stamp indicating when this data object was created. Format is a number expressed in Unix time as milliseconds (for example ``"1469498468.057"``).

            
          

          - **TerminationTime** *(datetime) --* 

            A time stamp indicating when this data object was terminated. Format is a number expressed in Unix time as milliseconds (for example ``"1469498468.057"``).

            
          

          - **Status** *(string) --* 

            Current status of the player session.

             

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

            
          

          - **IpAddress** *(string) --* 

            The IP address of the game session. To connect to a Amazon GameLift Servers game server, an app needs both the IP address and port number.

            
          

          - **DnsName** *(string) --* 

            The DNS identifier assigned to the instance that is running the game session. Values have the following format:

             

            
            * TLS-enabled fleets: ``<unique identifier>.<region identifier>.amazongamelift.com``.
             
            * Non-TLS-enabled fleets: ``ec2-<unique identifier>.compute.amazonaws.com``. (See `Amazon EC2 Instance IP Addressing <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-instance-addressing.html#concepts-public-addresses>`__.)
            

             

            When connecting to a game session that is running on a TLS-enabled fleet, you must use the DNS name, not the IP address.

            
          

          - **Port** *(integer) --* 

            Port number for the game session. To connect to a Amazon GameLift Servers server process, an app needs both the IP address and port number.

            
          

          - **PlayerData** *(string) --* 

            Developer-defined information related to a player. Amazon GameLift Servers does not use this data, so it can be formatted as needed for use in the game.

            
      
    
      

      - **NextToken** *(string) --* 

        A token that indicates where to resume retrieving results on the next call to this operation. If no token is returned, these results represent the end of the list.

        
  
  **Exceptions**
  
  *   :py:class:`GameLift.Client.exceptions.InternalServiceException`

  
  *   :py:class:`GameLift.Client.exceptions.NotFoundException`

  
  *   :py:class:`GameLift.Client.exceptions.InvalidRequestException`

  
  *   :py:class:`GameLift.Client.exceptions.UnauthorizedException`

  