getFindingHistory method

Future<GetFindingHistoryResponse> getFindingHistory({ required AwsSecurityFindingIdentifier findingIdentifier, DateTime? endTime, int? maxResults, String? nextToken, DateTime? startTime, })

Returns the history of a Security Hub CSPM finding. The history includes changes made to any fields in the Amazon Web Services Security Finding Format (ASFF) except top-level timestamp fields, such as the CreatedAt and UpdatedAt fields.

This operation might return fewer results than the maximum number of results (MaxResults) specified in a request, even when more results are available. If this occurs, the response includes a NextToken value, which you should use to retrieve the next set of results in the response. The presence of a NextToken value in a response doesn't necessarily indicate that the results are incomplete. However, you should continue to specify a NextToken value until you receive a response that doesn't include this value.

May throw InternalException. May throw InvalidAccessException. May throw InvalidInputException. May throw LimitExceededException.

Parameter endTime : An ISO 8601-formatted timestamp that indicates the end time of the requested finding history.

If you provide values for both StartTime and EndTime, Security Hub CSPM returns finding history for the specified time period. If you provide a value for StartTime but not for EndTime, Security Hub CSPM returns finding history from the StartTime to the time at which the API is called. If you provide a value for EndTime but not for StartTime, Security Hub CSPM returns finding history from the CreatedAt timestamp of the finding to the EndTime. If you provide neither StartTime nor EndTime, Security Hub CSPM returns finding history from the CreatedAt timestamp of the finding to the time at which the API is called. In all of these scenarios, the response is limited to 100 results.

For more information about the validation and formatting of timestamp fields in Security Hub CSPM, see Timestamps.

Parameter maxResults : The maximum number of results to be returned. If you don’t provide it, Security Hub CSPM returns up to 100 results of finding history.

Parameter nextToken : A token for pagination purposes. Provide NULL as the initial value. In subsequent requests, provide the token included in the response to get up to an additional 100 results of finding history. If you don’t provide NextToken, Security Hub CSPM returns up to 100 results of finding history for each request.

Parameter startTime : A timestamp that indicates the start time of the requested finding history.

If you provide values for both StartTime and EndTime, Security Hub CSPM returns finding history for the specified time period. If you provide a value for StartTime but not for EndTime, Security Hub CSPM returns finding history from the StartTime to the time at which the API is called. If you provide a value for EndTime but not for StartTime, Security Hub CSPM returns finding history from the CreatedAt timestamp of the finding to the EndTime. If you provide neither StartTime nor EndTime, Security Hub CSPM returns finding history from the CreatedAt timestamp of the finding to the time at which the API is called. In all of these scenarios, the response is limited to 100 results.

For more information about the validation and formatting of timestamp fields in Security Hub CSPM, see Timestamps.

Implementation

Future<GetFindingHistoryResponse> getFindingHistory({
  required AwsSecurityFindingIdentifier findingIdentifier,
  DateTime? endTime,
  int? maxResults,
  String? nextToken,
  DateTime? startTime,
}) async {
  _s.validateNumRange(
    'maxResults',
    maxResults,
    1,
    100,
  );
  final $payload = <String, dynamic>{
    'FindingIdentifier': findingIdentifier,
    if (endTime != null) 'EndTime': iso8601ToJson(endTime),
    if (maxResults != null) 'MaxResults': maxResults,
    if (nextToken != null) 'NextToken': nextToken,
    if (startTime != null) 'StartTime': iso8601ToJson(startTime),
  };
  final response = await _protocol.send(
    payload: $payload,
    method: 'POST',
    requestUri: '/findingHistory/get',
    exceptionFnMap: _exceptionFns,
  );
  return GetFindingHistoryResponse.fromJson(response);
}