AWS API Changes

2022/09/19 - AWS CloudTrail - 5 new api methods

Changes This release includes support for importing existing trails into CloudTrail Lake.

StartImport (new)

Starts an import of logged trail events from a source S3 bucket to a destination event data store.

When you start a new import, the Destinations and ImportSource parameters are required. Before starting a new import, disable any access control lists (ACLs) attached to the source S3 bucket. For more information about disabling ACLs, see Controlling ownership of objects and disabling ACLs for your bucket .

When you retry an import, the ImportID parameter is required.

See also: AWS API Documentation

Request Syntax

client.start_import(
    Destinations=[
        'string',
    ],
    ImportSource={
        'S3': {
            'S3LocationUri': 'string',
            'S3BucketRegion': 'string',
            'S3BucketAccessRoleArn': 'string'
        }
    },
    StartEventTime=datetime(2015, 1, 1),
    EndEventTime=datetime(2015, 1, 1),
    ImportId='string'
)

type Destinations

list

param Destinations

The destination event data store. Use this parameter for a new import.

(string) --

type ImportSource

dict

param ImportSource

The source S3 bucket for the import. Use this parameter for a new import.

S3 (dict) -- [REQUIRED]

The source S3 bucket.
- S3LocationUri (string) -- [REQUIRED]
  
  The URI for the source S3 bucket.
- S3BucketRegion (string) -- [REQUIRED]
  
  The region associated with the source S3 bucket.
- S3BucketAccessRoleArn (string) -- [REQUIRED]
  
  The IAM ARN role used to access the source S3 bucket.

type StartEventTime

datetime

param StartEventTime

Use with EndEventTime to bound a StartImport request, and limit imported trail events to only those events logged within a specified time period.

type EndEventTime

datetime

param EndEventTime

Use with StartEventTime to bound a StartImport request, and limit imported trail events to only those events logged within a specified time period.

type ImportId

string

param ImportId

The ID of the import. Use this parameter when you are retrying an import.

rtype

dict

returns

Response Syntax

{
    'ImportId': 'string',
    'Destinations': [
        'string',
    ],
    'ImportSource': {
        'S3': {
            'S3LocationUri': 'string',
            'S3BucketRegion': 'string',
            'S3BucketAccessRoleArn': 'string'
        }
    },
    'StartEventTime': datetime(2015, 1, 1),
    'EndEventTime': datetime(2015, 1, 1),
    'ImportStatus': 'INITIALIZING'|'IN_PROGRESS'|'FAILED'|'STOPPED'|'COMPLETED',
    'CreatedTimestamp': datetime(2015, 1, 1),
    'UpdatedTimestamp': datetime(2015, 1, 1)
}

Response Structure

(dict) --
- ImportId (string) --
  
  The ID of the import.
- Destinations (list) --
  
  The destination event data store.
  - (string) --
- ImportSource (dict) --
  
  The source S3 bucket.
  - S3 (dict) --
    
    The source S3 bucket.
    - S3LocationUri (string) --
      
      The URI for the source S3 bucket.
    - S3BucketRegion (string) --
      
      The region associated with the source S3 bucket.
    - S3BucketAccessRoleArn (string) --
      
      The IAM ARN role used to access the source S3 bucket.
- StartEventTime (datetime) --
  
  Used with EndEventTime to bound a StartImport request, and limit imported trail events to only those events logged within a specified time period.
- EndEventTime (datetime) --
  
  Used with StartEventTime to bound a StartImport request, and limit imported trail events to only those events logged within a specified time period.
- ImportStatus (string) --
  
  Shows the status of the import after a StartImport request. An import finishes with a status of COMPLETED if there were no failures, or FAILED if there were failures.
- CreatedTimestamp (datetime) --
  
  The timestamp for the import's creation.
- UpdatedTimestamp (datetime) --
  
  The timestamp of the import's last update, if applicable.

GetImport (new)

Link ¶

Returns information for the specified import.

See also: AWS API Documentation

Request Syntax

client.get_import(
    ImportId='string'
)

type ImportId

string

param ImportId

[REQUIRED]

The ID for the import.

rtype

dict

returns

Response Syntax

{
    'ImportId': 'string',
    'Destinations': [
        'string',
    ],
    'ImportSource': {
        'S3': {
            'S3LocationUri': 'string',
            'S3BucketRegion': 'string',
            'S3BucketAccessRoleArn': 'string'
        }
    },
    'StartEventTime': datetime(2015, 1, 1),
    'EndEventTime': datetime(2015, 1, 1),
    'ImportStatus': 'INITIALIZING'|'IN_PROGRESS'|'FAILED'|'STOPPED'|'COMPLETED',
    'CreatedTimestamp': datetime(2015, 1, 1),
    'UpdatedTimestamp': datetime(2015, 1, 1),
    'ImportStatistics': {
        'PrefixesFound': 123,
        'PrefixesCompleted': 123,
        'FilesCompleted': 123,
        'EventsCompleted': 123,
        'FailedEntries': 123
    }
}

Response Structure

(dict) --
- ImportId (string) --
  
  The ID of the import.
- Destinations (list) --
  
  The destination event data store.
  - (string) --
- ImportSource (dict) --
  
  The source S3 bucket.
  - S3 (dict) --
    
    The source S3 bucket.
    - S3LocationUri (string) --
      
      The URI for the source S3 bucket.
    - S3BucketRegion (string) --
      
      The region associated with the source S3 bucket.
    - S3BucketAccessRoleArn (string) --
      
      The IAM ARN role used to access the source S3 bucket.
- StartEventTime (datetime) --
  
  Used with EndEventTime to bound a StartImport request, and limit imported trail events to only those events logged within a specified time period.
- EndEventTime (datetime) --
  
  Used with StartEventTime to bound a StartImport request, and limit imported trail events to only those events logged within a specified time period.
- ImportStatus (string) --
  
  The status of the import.
- CreatedTimestamp (datetime) --
  
  The timestamp of the import's creation.
- UpdatedTimestamp (datetime) --
  
  The timestamp of when the import was updated.
- ImportStatistics (dict) --
  
  Provides statistics for the import.
  - PrefixesFound (integer) --
    
    The number of S3 prefixes found for the import.
  - PrefixesCompleted (integer) --
    
    The number of S3 prefixes that completed import.
  - FilesCompleted (integer) --
    
    The number of files that completed import.
  - EventsCompleted (integer) --
    
    The number of trail events imported.
  - FailedEntries (integer) --
    
    The number of failed entries.

ListImports (new)

Link ¶

Returns information on all imports, or a select set of imports by ImportStatus or Destination .

See also: AWS API Documentation

Request Syntax

client.list_imports(
    MaxResults=123,
    Destination='string',
    ImportStatus='INITIALIZING'|'IN_PROGRESS'|'FAILED'|'STOPPED'|'COMPLETED',
    NextToken='string'
)

type MaxResults

integer

param MaxResults

The maximum number of imports to display on a single page.

type Destination

string

param Destination

The destination event data store.

type ImportStatus

string

param ImportStatus

The status of the import.

type NextToken

string

param NextToken

A token you can use to get the next page of import results.

rtype

dict

returns

Response Syntax

{
    'Imports': [
        {
            'ImportId': 'string',
            'ImportStatus': 'INITIALIZING'|'IN_PROGRESS'|'FAILED'|'STOPPED'|'COMPLETED',
            'Destinations': [
                'string',
            ],
            'CreatedTimestamp': datetime(2015, 1, 1),
            'UpdatedTimestamp': datetime(2015, 1, 1)
        },
    ],
    'NextToken': 'string'
}

Response Structure

(dict) --
- Imports (list) --
  
  The list of returned imports.
  - (dict) --
    
    Contains information about an import that was returned by a lookup request.
    - ImportId (string) --
      
      The ID of the import.
    - ImportStatus (string) --
      
      The status of the import.
    - Destinations (list) --
      
      The destination event data store.
      - (string) --
    - CreatedTimestamp (datetime) --
      
      The timestamp of the import's creation.
    - UpdatedTimestamp (datetime) --
      
      The timestamp of the import's last update.
- NextToken (string) --
  
  A token you can use to get the next page of import results.

StopImport (new)

Link ¶

Stops a specified import.

See also: AWS API Documentation

Request Syntax

client.stop_import(
    ImportId='string'
)

type ImportId

string

param ImportId

[REQUIRED]

The ID of the import.

rtype

dict

returns

Response Syntax

{
    'ImportId': 'string',
    'ImportSource': {
        'S3': {
            'S3LocationUri': 'string',
            'S3BucketRegion': 'string',
            'S3BucketAccessRoleArn': 'string'
        }
    },
    'Destinations': [
        'string',
    ],
    'ImportStatus': 'INITIALIZING'|'IN_PROGRESS'|'FAILED'|'STOPPED'|'COMPLETED',
    'CreatedTimestamp': datetime(2015, 1, 1),
    'UpdatedTimestamp': datetime(2015, 1, 1),
    'StartEventTime': datetime(2015, 1, 1),
    'EndEventTime': datetime(2015, 1, 1),
    'ImportStatistics': {
        'PrefixesFound': 123,
        'PrefixesCompleted': 123,
        'FilesCompleted': 123,
        'EventsCompleted': 123,
        'FailedEntries': 123
    }
}

Response Structure

(dict) --
- ImportId (string) --
  
  The ID for the import.
- ImportSource (dict) --
  
  The source S3 bucket.
  - S3 (dict) --
    
    The source S3 bucket.
    - S3LocationUri (string) --
      
      The URI for the source S3 bucket.
    - S3BucketRegion (string) --
      
      The region associated with the source S3 bucket.
    - S3BucketAccessRoleArn (string) --
      
      The IAM ARN role used to access the source S3 bucket.
- Destinations (list) --
  
  The destination event data store.
  - (string) --
- ImportStatus (string) --
  
  The status of the import.
- CreatedTimestamp (datetime) --
  
  The timestamp of the import's creation.
- UpdatedTimestamp (datetime) --
  
  The timestamp of the import's last update.
- StartEventTime (datetime) --
  
  Used with EndEventTime to bound a StartImport request, and limit imported trail events to only those events logged within a specified time period.
- EndEventTime (datetime) --
  
  Used with StartEventTime to bound a StartImport request, and limit imported trail events to only those events logged within a specified time period.
- ImportStatistics (dict) --
  
  Returns information on the stopped import.
  - PrefixesFound (integer) --
    
    The number of S3 prefixes found for the import.
  - PrefixesCompleted (integer) --
    
    The number of S3 prefixes that completed import.
  - FilesCompleted (integer) --
    
    The number of files that completed import.
  - EventsCompleted (integer) --
    
    The number of trail events imported.
  - FailedEntries (integer) --
    
    The number of failed entries.

ListImportFailures (new)

Link ¶

Returns a list of failures for the specified import.

See also: AWS API Documentation

Request Syntax

client.list_import_failures(
    ImportId='string',
    MaxResults=123,
    NextToken='string'
)

type ImportId

string

param ImportId

[REQUIRED]

The ID of the import.

type MaxResults

integer

param MaxResults

The maximum number of failures to display on a single page.

type NextToken

string

param NextToken

A token you can use to get the next page of import failures.

rtype

dict

returns

Response Syntax

{
    'Failures': [
        {
            'Location': 'string',
            'Status': 'FAILED'|'RETRY'|'SUCCEEDED',
            'ErrorType': 'string',
            'ErrorMessage': 'string',
            'LastUpdatedTime': datetime(2015, 1, 1)
        },
    ],
    'NextToken': 'string'
}

Response Structure

(dict) --
- Failures (list) --
  
  Contains information about the import failures.
  - (dict) --
    
    Provides information about an import failure.
    - Location (string) --
      
      The location of the failure in the S3 bucket.
    - Status (string) --
      
      The status of the import.
    - ErrorType (string) --
      
      The type of import error.
    - ErrorMessage (string) --
      
      Provides the reason the import failed.
    - LastUpdatedTime (datetime) --
      
      When the import was last updated.
- NextToken (string) --
  
  A token you can use to get the next page of results.