AWS API Changes

2022/03/02 - AWS CloudTrail - 4 updated api methods

Changes Add bytesScanned field into responses of DescribeQuery and GetQueryResults.

CancelQuery (updated)

Link ¶
Changes (response)

{'QueryStatus': {'TIMED_OUT'}}

Cancels a query if the query is not in a terminated state, such as CANCELLED, FAILED, TIMED_OUT, or FINISHED. You must specify an ARN value for EventDataStore. The ID of the query that you want to cancel is also required. When you run CancelQuery, the query status might show as CANCELLED even if the operation is not yet finished.

See also: AWS API Documentation

Request Syntax

client.cancel_query(
    EventDataStore='string',
    QueryId='string'
)

type EventDataStore:

string

param EventDataStore:

[REQUIRED]

The ARN (or the ID suffix of the ARN) of an event data store on which the specified query is running.

type QueryId:

string

param QueryId:

[REQUIRED]

The ID of the query that you want to cancel. The QueryId comes from the response of a StartQuery operation.

rtype:

dict

returns:

Response Syntax

{
    'QueryId': 'string',
    'QueryStatus': 'QUEUED'|'RUNNING'|'FINISHED'|'FAILED'|'CANCELLED'|'TIMED_OUT'
}

Response Structure

(dict) --
- QueryId (string) --
  
  The ID of the canceled query.
- QueryStatus (string) --
  
  Shows the status of a query after a CancelQuery request. Typically, the values shown are either RUNNING or CANCELLED.

DescribeQuery (updated)

Link ¶
Changes (response)

{'QueryStatistics': {'BytesScanned': 'long'}, 'QueryStatus': {'TIMED_OUT'}}

Returns metadata about a query, including query run time in milliseconds, number of events scanned and matched, and query status. You must specify an ARN for EventDataStore, and a value for QueryID.

See also: AWS API Documentation

Request Syntax

client.describe_query(
    EventDataStore='string',
    QueryId='string'
)

type EventDataStore:

string

param EventDataStore:

[REQUIRED]

The ARN (or the ID suffix of the ARN) of an event data store on which the specified query was run.

type QueryId:

string

param QueryId:

[REQUIRED]

The query ID.

rtype:

dict

returns:

Response Syntax

{
    'QueryId': 'string',
    'QueryString': 'string',
    'QueryStatus': 'QUEUED'|'RUNNING'|'FINISHED'|'FAILED'|'CANCELLED'|'TIMED_OUT',
    'QueryStatistics': {
        'EventsMatched': 123,
        'EventsScanned': 123,
        'BytesScanned': 123,
        'ExecutionTimeInMillis': 123,
        'CreationTime': datetime(2015, 1, 1)
    },
    'ErrorMessage': 'string'
}

Response Structure

(dict) --
- QueryId (string) --
  
  The ID of the query.
- QueryString (string) --
  
  The SQL code of a query.
- QueryStatus (string) --
  
  The status of a query. Values for QueryStatus include QUEUED, RUNNING, FINISHED, FAILED, TIMED_OUT, or CANCELLED
- QueryStatistics (dict) --
  
  Metadata about a query, including the number of events that were matched, the total number of events scanned, the query run time in milliseconds, and the query's creation time.
  - EventsMatched (integer) --
    
    The number of events that matched a query.
  - EventsScanned (integer) --
    
    The number of events that the query scanned in the event data store.
  - BytesScanned (integer) --
    
    The total bytes that the query scanned in the event data store. This value matches the number of bytes for which your account is billed for the query, unless the query is still running.
  - ExecutionTimeInMillis (integer) --
    
    The query's run time, in milliseconds.
  - CreationTime (datetime) --
    
    The creation time of the query.
- ErrorMessage (string) --
  
  The error message returned if a query failed.

GetQueryResults (updated)

Link ¶
Changes (response)

{'QueryStatistics': {'BytesScanned': 'long'}, 'QueryStatus': {'TIMED_OUT'}}

Gets event data results of a query. You must specify the QueryID value returned by the StartQuery operation, and an ARN for EventDataStore.

See also: AWS API Documentation

Request Syntax

client.get_query_results(
    EventDataStore='string',
    QueryId='string',
    NextToken='string',
    MaxQueryResults=123
)

type EventDataStore:

string

param EventDataStore:

[REQUIRED]

The ARN (or ID suffix of the ARN) of the event data store against which the query was run.

type QueryId:

string

param QueryId:

[REQUIRED]

The ID of the query for which you want to get results.

type NextToken:

string

param NextToken:

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

type MaxQueryResults:

integer

param MaxQueryResults:

The maximum number of query results to display on a single page.

rtype:

dict

returns:

Response Syntax

{
    'QueryStatus': 'QUEUED'|'RUNNING'|'FINISHED'|'FAILED'|'CANCELLED'|'TIMED_OUT',
    'QueryStatistics': {
        'ResultsCount': 123,
        'TotalResultsCount': 123,
        'BytesScanned': 123
    },
    'QueryResultRows': [
        [
            {
                'string': 'string'
            },
        ],
    ],
    'NextToken': 'string',
    'ErrorMessage': 'string'
}

Response Structure

(dict) --
- QueryStatus (string) --
  
  The status of the query. Values include QUEUED, RUNNING, FINISHED, FAILED, TIMED_OUT, or CANCELLED.
- QueryStatistics (dict) --
  
  Shows the count of query results.
  - ResultsCount (integer) --
    
    The number of results returned.
  - TotalResultsCount (integer) --
    
    The total number of results returned by a query.
  - BytesScanned (integer) --
    
    The total bytes that the query scanned in the event data store. This value matches the number of bytes for which your account is billed for the query, unless the query is still running.
- QueryResultRows (list) --
  
  Contains the individual event results of the query.
  - (list) --
    - (dict) --
      - (string) --
        
        (string) --
- NextToken (string) --
  
  A token you can use to get the next page of query results.
- ErrorMessage (string) --
  
  The error message returned if a query failed.

ListQueries (updated)

Link ¶
Changes (request, response)
Request

{'QueryStatus': {'TIMED_OUT'}}

Response

{'Queries': {'QueryStatus': {'TIMED_OUT'}}}

Returns a list of queries and query statuses for the past seven days. You must specify an ARN value for EventDataStore. Optionally, to shorten the list of results, you can specify a time range, formatted as timestamps, by adding StartTime and EndTime parameters, and a QueryStatus value. Valid values for QueryStatus include QUEUED, RUNNING, FINISHED, FAILED, TIMED_OUT, or CANCELLED.

See also: AWS API Documentation

Request Syntax

client.list_queries(
    EventDataStore='string',
    NextToken='string',
    MaxResults=123,
    StartTime=datetime(2015, 1, 1),
    EndTime=datetime(2015, 1, 1),
    QueryStatus='QUEUED'|'RUNNING'|'FINISHED'|'FAILED'|'CANCELLED'|'TIMED_OUT'
)

type EventDataStore:

string

param EventDataStore:

[REQUIRED]

The ARN (or the ID suffix of the ARN) of an event data store on which queries were run.

type NextToken:

string

param NextToken:

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

type MaxResults:

integer

param MaxResults:

The maximum number of queries to show on a page.

type StartTime:

datetime

param StartTime:

Use with EndTime to bound a ListQueries request, and limit its results to only those queries run within a specified time period.

type EndTime:

datetime

param EndTime:

Use with StartTime to bound a ListQueries request, and limit its results to only those queries run within a specified time period.

type QueryStatus:

string

param QueryStatus:

The status of queries that you want to return in results. Valid values for QueryStatus include QUEUED, RUNNING, FINISHED, FAILED, TIMED_OUT, or CANCELLED.

rtype:

dict

returns:

Response Syntax

{
    'Queries': [
        {
            'QueryId': 'string',
            'QueryStatus': 'QUEUED'|'RUNNING'|'FINISHED'|'FAILED'|'CANCELLED'|'TIMED_OUT',
            'CreationTime': datetime(2015, 1, 1)
        },
    ],
    'NextToken': 'string'
}

Response Structure

(dict) --
- Queries (list) --
  
  Lists matching query results, and shows query ID, status, and creation time of each query.
  - (dict) --
    
    A SQL string of criteria about events that you want to collect in an event data store.
    - QueryId (string) --
      
      The ID of a query.
    - QueryStatus (string) --
      
      The status of the query. This can be QUEUED, RUNNING, FINISHED, FAILED, TIMED_OUT, or CANCELLED.
    - CreationTime (datetime) --
      
      The creation time of a query.
- NextToken (string) --
  
  A token you can use to get the next page of results.