AWS API Changes

2021/11/15 - Amazon Simple Systems Manager (SSM) - 2 updated api methods

Changes Adds support for Session Reason and Max Session Duration for Systems Manager Session Manager.

DescribeSessions (updated)

Link ¶
Changes (response)

{'Sessions': {'MaxSessionDuration': 'string', 'Reason': 'string'}}

Retrieves a list of all active sessions (both connected and disconnected) or terminated sessions from the past 30 days.

See also: AWS API Documentation

Request Syntax

client.describe_sessions(
    State='Active'|'History',
    MaxResults=123,
    NextToken='string',
    Filters=[
        {
            'key': 'InvokedAfter'|'InvokedBefore'|'Target'|'Owner'|'Status'|'SessionId',
            'value': 'string'
        },
    ]
)

type State

string

param State

[REQUIRED]

The session status to retrieve a list of sessions for. For example, "Active".

type MaxResults

integer

param MaxResults

The maximum number of items to return for this call. The call also returns a token that you can specify in a subsequent call to get the next set of results.

type NextToken

string

param NextToken

The token for the next set of items to return. (You received this token from a previous call.)

type Filters

list

param Filters

One or more filters to limit the type of sessions returned by the request.

(dict) --

Describes a filter for Session Manager information.
- key (string) -- [REQUIRED]
  
  The name of the filter.
- value (string) -- [REQUIRED]
  
  The filter value. Valid values for each filter key are as follows:
  - InvokedAfter: Specify a timestamp to limit your results. For example, specify 2018-08-29T00:00:00Z to see sessions that started August 29, 2018, and later.
  - InvokedBefore: Specify a timestamp to limit your results. For example, specify 2018-08-29T00:00:00Z to see sessions that started before August 29, 2018.
  - Target: Specify an instance to which session connections have been made.
  - Owner: Specify an Amazon Web Services user account to see a list of sessions started by that user.
  - Status: Specify a valid session status to see a list of all sessions with that status. Status values you can specify include:
    - Connected
    - Connecting
    - Disconnected
    - Terminated
    - Terminating
    - Failed
  - SessionId: Specify a session ID to return details about the session.

rtype

dict

returns

Response Syntax

{
    'Sessions': [
        {
            'SessionId': 'string',
            'Target': 'string',
            'Status': 'Connected'|'Connecting'|'Disconnected'|'Terminated'|'Terminating'|'Failed',
            'StartDate': datetime(2015, 1, 1),
            'EndDate': datetime(2015, 1, 1),
            'DocumentName': 'string',
            'Owner': 'string',
            'Reason': 'string',
            'Details': 'string',
            'OutputUrl': {
                'S3OutputUrl': 'string',
                'CloudWatchOutputUrl': 'string'
            },
            'MaxSessionDuration': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

(dict) --
- Sessions (list) --
  
  A list of sessions meeting the request parameters.
  - (dict) --
    
    Information about a Session Manager connection to an instance.
    - SessionId (string) --
      
      The ID of the session.
    - Target (string) --
      
      The instance that the Session Manager session connected to.
    - Status (string) --
      
      The status of the session. For example, "Connected" or "Terminated".
    - StartDate (datetime) --
      
      The date and time, in ISO-8601 Extended format, when the session began.
    - EndDate (datetime) --
      
      The date and time, in ISO-8601 Extended format, when the session was terminated.
    - DocumentName (string) --
      
      The name of the Session Manager SSM document used to define the parameters and plugin settings for the session. For example, SSM-SessionManagerRunShell .
    - Owner (string) --
      
      The ID of the Amazon Web Services user account that started the session.
    - Reason (string) --
      
      The reason for connecting to the instance.
    - Details (string) --
      
      Reserved for future use.
    - OutputUrl (dict) --
      
      Reserved for future use.
      - S3OutputUrl (string) --
        
        Reserved for future use.
      - CloudWatchOutputUrl (string) --
        
        Reserved for future use.
    - MaxSessionDuration (string) --
      
      The maximum duration of a session before it terminates.
- NextToken (string) --
  
  The token for the next set of items to return. (You received this token from a previous call.)

StartSession (updated)

Link ¶
Changes (request)

{'Reason': 'string'}

Initiates a connection to a target (for example, an instance) for a Session Manager session. Returns a URL and token that can be used to open a WebSocket connection for sending input and receiving outputs.

Note

Amazon Web Services CLI usage: start-session is an interactive command that requires the Session Manager plugin to be installed on the client machine making the call. For information, see Install the Session Manager plugin for the Amazon Web Services CLI in the Amazon Web Services Systems Manager User Guide .

Amazon Web Services Tools for PowerShell usage: Start-SSMSession isn't currently supported by Amazon Web Services Tools for PowerShell on Windows local machines.

See also: AWS API Documentation

Request Syntax

client.start_session(
    Target='string',
    DocumentName='string',
    Reason='string',
    Parameters={
        'string': [
            'string',
        ]
    }
)

type Target

string

param Target

[REQUIRED]

The instance to connect to for the session.

type DocumentName

string

param DocumentName

The name of the SSM document to define the parameters and plugin settings for the session. For example, SSM-SessionManagerRunShell . You can call the GetDocument API to verify the document exists before attempting to start a session. If no document name is provided, a shell to the instance is launched by default.

type Reason

string

param Reason

The reason for connecting to the instance. This value is included in the details for the Amazon CloudWatch Events event created when you start the session.

type Parameters

dict

param Parameters

Reserved for future use.

(string) --
- (list) --
  - (string) --

rtype

dict

returns

Response Syntax

{
    'SessionId': 'string',
    'TokenValue': 'string',
    'StreamUrl': 'string'
}

Response Structure

(dict) --
- SessionId (string) --
  
  The ID of the session.
- TokenValue (string) --
  
  An encrypted token value containing session and caller information. Used to authenticate the connection to the instance.
- StreamUrl (string) --
  
  A URL back to SSM Agent on the instance that the Session Manager client uses to send commands and receive output from the instance. Format: wss://ssmmessages.**region** .amazonaws.com/v1/data-channel/**session-id** ?stream=(input|output)
  
  region represents the Region identifier for an Amazon Web Services Region supported by Amazon Web Services Systems Manager, such as us-east-2 for the US East (Ohio) Region. For a list of supported region values, see the Region column in Systems Manager service endpoints in the Amazon Web Services General Reference .
  
  session-id represents the ID of a Session Manager session, such as 1a2b3c4dEXAMPLE .