2025/02/13 - AWS Storage Gateway - 5 new api methods
Changes This release adds support for generating cache reports on S3 File Gateways for files that fail to upload.
Cancels generation of a specified cache report. You can use this operation to manually cancel an IN-PROGRESS report for any reason. This action changes the report status from IN-PROGRESS to CANCELLED. You can only cancel in-progress reports. If the the report you attempt to cancel is in FAILED, ERROR, or COMPLETED state, the cancel operation returns an error.
See also: AWS API Documentation
Request Syntax
client.cancel_cache_report(
CacheReportARN='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the cache report you want to cancel.
dict
Response Syntax
{
'CacheReportARN': 'string'
}
Response Structure
(dict) --
CacheReportARN (string) --
The Amazon Resource Name (ARN) of the cache report you want to cancel.
Returns information about the specified cache report, including completion status and generation progress.
See also: AWS API Documentation
Request Syntax
client.describe_cache_report(
CacheReportARN='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the cache report you want to describe.
dict
Response Syntax
{
'CacheReportInfo': {
'CacheReportARN': 'string',
'CacheReportStatus': 'IN_PROGRESS'|'COMPLETED'|'CANCELED'|'FAILED'|'ERROR',
'ReportCompletionPercent': 123,
'EndTime': datetime(2015, 1, 1),
'Role': 'string',
'FileShareARN': 'string',
'LocationARN': 'string',
'StartTime': datetime(2015, 1, 1),
'InclusionFilters': [
{
'Name': 'UploadState'|'UploadFailureReason',
'Values': [
'string',
]
},
],
'ExclusionFilters': [
{
'Name': 'UploadState'|'UploadFailureReason',
'Values': [
'string',
]
},
],
'ReportName': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
}
}
Response Structure
(dict) --
CacheReportInfo (dict) --
Contains all informational fields associated with a cache report. Includes name, ARN, tags, status, progress, filters, start time, and end time.
CacheReportARN (string) --
The Amazon Resource Name (ARN) of the cache report you want to describe.
CacheReportStatus (string) --
The status of the specified cache report.
ReportCompletionPercent (integer) --
The percentage of the report generation process that has been completed at time of inquiry.
EndTime (datetime) --
The time at which the gateway stopped generating the cache report.
Role (string) --
The ARN of the IAM role that an S3 File Gateway assumes when it accesses the underlying storage.
FileShareARN (string) --
The Amazon Resource Name (ARN) of the file share.
LocationARN (string) --
The ARN of the Amazon S3 bucket location where the cache report is saved.
StartTime (datetime) --
The time at which the gateway started generating the cache report.
InclusionFilters (list) --
The list of filters and parameters that determine which files are included in the report.
(dict) --
A list of filter parameters and associated values that determine which files are included or excluded from a cache report created by a StartCacheReport request. Multiple instances of the same filter parameter are combined with an OR operation, while different parameters are combined with an AND operation.
Name (string) --
The parameter name for a filter that determines which files are included or excluded from a cache report.
Valid Names:
UploadFailureReason | UploadState
Values (list) --
The parameter value for a filter that determines which files are included or excluded from a cache report.
Valid UploadFailureReason Values:
InaccessibleStorageClass | InvalidObjectState | ObjectMissing | S3AccessDenied
Valid UploadState Values:
FailingUpload
(string) --
ExclusionFilters (list) --
The list of filters and parameters that determine which files are excluded from the report.
(dict) --
A list of filter parameters and associated values that determine which files are included or excluded from a cache report created by a StartCacheReport request. Multiple instances of the same filter parameter are combined with an OR operation, while different parameters are combined with an AND operation.
Name (string) --
The parameter name for a filter that determines which files are included or excluded from a cache report.
Valid Names:
UploadFailureReason | UploadState
Values (list) --
The parameter value for a filter that determines which files are included or excluded from a cache report.
Valid UploadFailureReason Values:
InaccessibleStorageClass | InvalidObjectState | ObjectMissing | S3AccessDenied
Valid UploadState Values:
FailingUpload
(string) --
ReportName (string) --
The file name of the completed cache report object stored in Amazon S3.
Tags (list) --
The list of key/value tags associated with the report.
(dict) --
A key-value pair that helps you manage, filter, and search for your resource. Allowed characters: letters, white space, and numbers, representable in UTF-8, and the following characters: + - = . _ : /.
Key (string) --
Tag key. The key can't start with aws:.
Value (string) --
Value of the tag key.
Deletes the specified cache report and any associated tags from the Storage Gateway database. You can only delete completed reports. If the status of the report you attempt to delete still IN-PROGRESS, the delete operation returns an error. You can use CancelCacheReport to cancel an IN-PROGRESS report.
See also: AWS API Documentation
Request Syntax
client.delete_cache_report(
CacheReportARN='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the cache report you want to delete.
dict
Response Syntax
{
'CacheReportARN': 'string'
}
Response Structure
(dict) --
CacheReportARN (string) --
The Amazon Resource Name (ARN) of the cache report you want to delete.
Returns a list of existing cache reports for all file shares associated with your Amazon Web Services account. This list includes all information provided by the DescribeCacheReport action, such as report name, status, completion progress, start time, end time, filters, and tags.
See also: AWS API Documentation
Request Syntax
client.list_cache_reports(
Marker='string'
)
string
Opaque pagination token returned from a previous ListCacheReports operation. If present, Marker specifies where to continue the list from after a previous call to ListCacheReports. Optional.
dict
Response Syntax
{
'CacheReportList': [
{
'CacheReportARN': 'string',
'CacheReportStatus': 'IN_PROGRESS'|'COMPLETED'|'CANCELED'|'FAILED'|'ERROR',
'ReportCompletionPercent': 123,
'EndTime': datetime(2015, 1, 1),
'Role': 'string',
'FileShareARN': 'string',
'LocationARN': 'string',
'StartTime': datetime(2015, 1, 1),
'InclusionFilters': [
{
'Name': 'UploadState'|'UploadFailureReason',
'Values': [
'string',
]
},
],
'ExclusionFilters': [
{
'Name': 'UploadState'|'UploadFailureReason',
'Values': [
'string',
]
},
],
'ReportName': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
},
],
'Marker': 'string'
}
Response Structure
(dict) --
CacheReportList (list) --
A list of existing cache reports for all file shares associated with your Amazon Web Services account. This list includes all information provided by the DescribeCacheReport action, such as report status, completion progress, start time, end time, filters, and tags.
(dict) --
Contains all informational fields associated with a cache report. Includes name, ARN, tags, status, progress, filters, start time, and end time.
CacheReportARN (string) --
The Amazon Resource Name (ARN) of the cache report you want to describe.
CacheReportStatus (string) --
The status of the specified cache report.
ReportCompletionPercent (integer) --
The percentage of the report generation process that has been completed at time of inquiry.
EndTime (datetime) --
The time at which the gateway stopped generating the cache report.
Role (string) --
The ARN of the IAM role that an S3 File Gateway assumes when it accesses the underlying storage.
FileShareARN (string) --
The Amazon Resource Name (ARN) of the file share.
LocationARN (string) --
The ARN of the Amazon S3 bucket location where the cache report is saved.
StartTime (datetime) --
The time at which the gateway started generating the cache report.
InclusionFilters (list) --
The list of filters and parameters that determine which files are included in the report.
(dict) --
A list of filter parameters and associated values that determine which files are included or excluded from a cache report created by a StartCacheReport request. Multiple instances of the same filter parameter are combined with an OR operation, while different parameters are combined with an AND operation.
Name (string) --
The parameter name for a filter that determines which files are included or excluded from a cache report.
Valid Names:
UploadFailureReason | UploadState
Values (list) --
The parameter value for a filter that determines which files are included or excluded from a cache report.
Valid UploadFailureReason Values:
InaccessibleStorageClass | InvalidObjectState | ObjectMissing | S3AccessDenied
Valid UploadState Values:
FailingUpload
(string) --
ExclusionFilters (list) --
The list of filters and parameters that determine which files are excluded from the report.
(dict) --
A list of filter parameters and associated values that determine which files are included or excluded from a cache report created by a StartCacheReport request. Multiple instances of the same filter parameter are combined with an OR operation, while different parameters are combined with an AND operation.
Name (string) --
The parameter name for a filter that determines which files are included or excluded from a cache report.
Valid Names:
UploadFailureReason | UploadState
Values (list) --
The parameter value for a filter that determines which files are included or excluded from a cache report.
Valid UploadFailureReason Values:
InaccessibleStorageClass | InvalidObjectState | ObjectMissing | S3AccessDenied
Valid UploadState Values:
FailingUpload
(string) --
ReportName (string) --
The file name of the completed cache report object stored in Amazon S3.
Tags (list) --
The list of key/value tags associated with the report.
(dict) --
A key-value pair that helps you manage, filter, and search for your resource. Allowed characters: letters, white space, and numbers, representable in UTF-8, and the following characters: + - = . _ : /.
Key (string) --
Tag key. The key can't start with aws:.
Value (string) --
Value of the tag key.
Marker (string) --
If the request includes Marker, the response returns that value in this field.
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 permissions to list the entire Amazon S3 bucket associated with the specified file share.
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.
See also: AWS API Documentation
Request Syntax
client.start_cache_report(
FileShareARN='string',
Role='string',
LocationARN='string',
BucketRegion='string',
VPCEndpointDNSName='string',
InclusionFilters=[
{
'Name': 'UploadState'|'UploadFailureReason',
'Values': [
'string',
]
},
],
ExclusionFilters=[
{
'Name': 'UploadState'|'UploadFailureReason',
'Values': [
'string',
]
},
],
ClientToken='string',
Tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the file share.
string
[REQUIRED]
The ARN of the IAM role used when saving the cache report to Amazon S3.
string
[REQUIRED]
The ARN of the Amazon S3 bucket where the cache report will be saved.
string
[REQUIRED]
The Amazon Web Services Region of the Amazon S3 bucket associated with the file share for which you want to generate the cache report.
string
The DNS name of the VPC endpoint associated with the Amazon S3 where you want to save the cache report. Optional.
list
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.
(dict) --
A list of filter parameters and associated values that determine which files are included or excluded from a cache report created by a StartCacheReport request. Multiple instances of the same filter parameter are combined with an OR operation, while different parameters are combined with an AND operation.
Name (string) -- [REQUIRED]
The parameter name for a filter that determines which files are included or excluded from a cache report.
Valid Names:
UploadFailureReason | UploadState
Values (list) -- [REQUIRED]
The parameter value for a filter that determines which files are included or excluded from a cache report.
Valid UploadFailureReason Values:
InaccessibleStorageClass | InvalidObjectState | ObjectMissing | S3AccessDenied
Valid UploadState Values:
FailingUpload
(string) --
list
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.
(dict) --
A list of filter parameters and associated values that determine which files are included or excluded from a cache report created by a StartCacheReport request. Multiple instances of the same filter parameter are combined with an OR operation, while different parameters are combined with an AND operation.
Name (string) -- [REQUIRED]
The parameter name for a filter that determines which files are included or excluded from a cache report.
Valid Names:
UploadFailureReason | UploadState
Values (list) -- [REQUIRED]
The parameter value for a filter that determines which files are included or excluded from a cache report.
Valid UploadFailureReason Values:
InaccessibleStorageClass | InvalidObjectState | ObjectMissing | S3AccessDenied
Valid UploadState Values:
FailingUpload
(string) --
string
[REQUIRED]
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.
list
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.
(dict) --
A key-value pair that helps you manage, filter, and search for your resource. Allowed characters: letters, white space, and numbers, representable in UTF-8, and the following characters: + - = . _ : /.
Key (string) -- [REQUIRED]
Tag key. The key can't start with aws:.
Value (string) -- [REQUIRED]
Value of the tag key.
dict
Response Syntax
{
'CacheReportARN': 'string'
}
Response Structure
(dict) --
CacheReportARN (string) --
The Amazon Resource Name (ARN) of the cache report generated by the StartCacheReport request.