startCacheReport method

Future<StartCacheReportOutput> startCacheReport({ required String bucketRegion, required String clientToken, required String fileShareARN, required String locationARN, required String role, List<CacheReportFilter>? exclusionFilters, List<CacheReportFilter>? inclusionFilters, List<Tag>? tags, String? vPCEndpointDNSName, })

Starts generating a report of the file metadata currently cached by an S3 File Gateway for a specific file share. You can use this report to identify and resolve issues if you have files failing upload from your gateway to Amazon S3. The report is a CSV file containing a list of files which match the set of filter parameters you specify in the request. The following requirements must be met to successfully generate a cache report:

• You must have s3:PutObject and s3:AbortMultipartUpload permissions for the Amazon S3 bucket where you want to store the cache report.
• No other cache reports can currently be in-progress for the specified file share.
• There must be fewer than 10 existing cache reports for the specified file share.
• The gateway must be online and connected to Amazon Web Services.
• The root disk must have at least 20GB of free space when report generation starts.
• You must specify at least one value for InclusionFilters or ExclusionFilters in the request.

May throw InternalServerError. May throw InvalidGatewayRequestException.

Parameter bucketRegion : The Amazon Web Services Region of the Amazon S3 bucket where you want to save the cache report.

Parameter clientToken : A unique identifier that you use to ensure idempotent report generation if you need to retry an unsuccessful StartCacheReport request. If you retry a request, use the same ClientToken you specified in the initial request.

Parameter locationARN : The ARN of the Amazon S3 bucket where you want to save the cache report.

This field does not accept access point ARNs.

Parameter role : The ARN of the IAM role used when saving the cache report to Amazon S3.

Parameter exclusionFilters : The list of filters and parameters that determine which files are excluded from the report. You must specify at least one value for InclusionFilters or ExclusionFilters in a StartCacheReport request.

Parameter inclusionFilters : The list of filters and parameters that determine which files are included in the report. You must specify at least one value for InclusionFilters or ExclusionFilters in a StartCacheReport request.

Parameter tags : A list of up to 50 key/value tags that you can assign to the cache report. Using tags can help you categorize your reports and more easily locate them in search results.

Parameter vPCEndpointDNSName : The DNS name of the VPC endpoint associated with the Amazon S3 where you want to save the cache report. Optional.

Implementation

Future<StartCacheReportOutput> startCacheReport({
  required String bucketRegion,
  required String clientToken,
  required String fileShareARN,
  required String locationARN,
  required String role,
  List<CacheReportFilter>? exclusionFilters,
  List<CacheReportFilter>? inclusionFilters,
  List<Tag>? tags,
  String? vPCEndpointDNSName,
}) async {
  final headers = <String, String>{
    'Content-Type': 'application/x-amz-json-1.1',
    'X-Amz-Target': 'StorageGateway_20130630.StartCacheReport'
  };
  final jsonResponse = await _protocol.send(
    method: 'POST',
    requestUri: '/',
    exceptionFnMap: _exceptionFns,
    // TODO queryParams
    headers: headers,
    payload: {
      'BucketRegion': bucketRegion,
      'ClientToken': clientToken,
      'FileShareARN': fileShareARN,
      'LocationARN': locationARN,
      'Role': role,
      if (exclusionFilters != null) 'ExclusionFilters': exclusionFilters,
      if (inclusionFilters != null) 'InclusionFilters': inclusionFilters,
      if (tags != null) 'Tags': tags,
      if (vPCEndpointDNSName != null)
        'VPCEndpointDNSName': vPCEndpointDNSName,
    },
  );

  return StartCacheReportOutput.fromJson(jsonResponse.body);
}