GetBucketMetricsConfiguration
Note
This operation is not supported for directory buckets.
Gets a metrics configuration (specified by the metrics configuration ID) from the bucket. Note that this doesn't include the daily storage metrics.
To use this operation, you must have permissions to perform the
s3:GetMetricsConfiguration
action. The bucket owner has this permission by
default. The bucket owner can grant this permission to others. For more information about
permissions, see Permissions Related to Bucket Subresource Operations and Managing
Access Permissions to Your Amazon S3 Resources.
For information about CloudWatch request metrics for Amazon S3, see Monitoring Metrics with Amazon CloudWatch.
The following operations are related to
GetBucketMetricsConfiguration
:
Request Syntax
GET /?metrics&id=Id
HTTP/1.1
Host: Bucket
.s3.amazonaws.com
x-amz-expected-bucket-owner: ExpectedBucketOwner
URI Request Parameters
The request uses the following URI parameters.
- Bucket
-
The name of the bucket containing the metrics configuration to retrieve.
Required: Yes
- id
-
The ID used to identify the metrics configuration. The ID has a 64 character limit and can only contain letters, numbers, periods, dashes, and underscores.
Required: Yes
- x-amz-expected-bucket-owner
-
The account ID of the expected bucket owner. If the account ID that you provide does not match the actual owner of the bucket, the request fails with the HTTP status code
403 Forbidden
(access denied).
Request Body
The request does not have a request body.
Response Syntax
HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<MetricsConfiguration>
<Id>string</Id>
<Filter>
<AccessPointArn>string</AccessPointArn>
<And>
<AccessPointArn>string</AccessPointArn>
<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
...
</And>
<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
</Filter>
</MetricsConfiguration>
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in XML format by the service.
- MetricsConfiguration
-
Root level tag for the MetricsConfiguration parameters.
Required: Yes
- Filter
-
Specifies a metrics configuration filter. The metrics configuration will only include objects that meet the filter's criteria. A filter must be a prefix, an object tag, an access point ARN, or a conjunction (MetricsAndOperator).
Type: MetricsFilter data type
- Id
-
The ID used to identify the metrics configuration. The ID has a 64 character limit and can only contain letters, numbers, periods, dashes, and underscores.
Type: String
Examples
First Sample Request
Retrieve a metrics configuration that filters metrics based on a specified prefix.
GET /?metrics&id=Documents HTTP/1.1 Host: examplebucket.s3.<Region>.amazonaws.com x-amz-date: Thu, 15 Nov 2016 00:17:21 GMT Authorization: signatureValue
First Sample Response
This example illustrates one usage of GetBucketMetricsConfiguration.
HTTP/1.1 200 OK x-amz-id-2: ITnGT1y4REXAMPLEPi4hklTXouTf0hccUjo0iCPEXAMPLEutBj3M7fPGlWO2SEWp x-amz-request-id: 51991EXAMPLE5321 Date: Thu, 15 Nov 2016 00:17:22 GMT Server: AmazonS3 Content-Length: 180 <?xml version="1.0" encoding="UTF-8"?> <MetricsConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Id>Documents</Id> <Filter> <Prefix>documents/</Prefix> </Filter> </MetricsConfiguration>
Second Sample Request
Retrieve a metrics configuration that enables metrics for objects that start with a particular prefix and have specific tags applied.
GET /?metrics&id=ImportantBlueDocuments HTTP/1.1 Host: examplebucket.s3.<Region>.amazonaws.com x-amz-date: Thu, 15 Nov 2016 00:17:21 GMT Authorization: signatureValue
Second Sample Response
This example illustrates one usage of GetBucketMetricsConfiguration.
HTTP/1.1 200 OK x-amz-id-2: ITnGT1y4REXAMPLEPi4hklTXouTf0hccUjo0iCPEXAMPLEutBj3M7fPGlWO2SEWp x-amz-request-id: 51991EXAMPLE5321 Date: Thu, 15 Nov 2016 00:17:22 GMT Server: AmazonS3 Content-Length: 480 <?xml version="1.0" encoding="UTF-8"?> <MetricsConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Id>ImportantBlueDocuments</Id> <Filter> <And> <Prefix>documents/</Prefix> <Tag> <Key>priority</Key> <Value>high</Value> </Tag> <Tag> <Key>class</Key> <Value>blue</Value> </Tag> </And> </Filter> </MetricsConfiguration>
Third Sample Request
Retrieve a metrics configuration that enables metrics for a specific access point.
GET /?metrics&id=ImportantDocumentsAccessPoint HTTP/1.1 Host: examplebucket.s3.<Region>.amazonaws.com x-amz-date: Thu, 26 Aug 2021 00:17:21 GMT Authorization: signatureValue
Third Sample Response
This example illustrates one usage of GetBucketMetricsConfiguration.
HTTP/1.1 200 OK x-amz-id-2: ITnGT1y4REXAMPLEPi4hklTXouTf0hccUjo0iCPEXAMPLEutBj3M7fPGlWO2SEWp x-amz-request-id: 51991EXAMPLE5321 Date: Thu, 26 Aug 2021 00:17:22 GMT Server: AmazonS3 Content-Length: 480 <?xml version="1.0" encoding="UTF-8"?> <MetricsConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Id>ImportantDocumentsAccessPoint</Id> <Filter> <AccessPointArn>arn:aws:s3:us-west-2:123456789012:accesspoint/test</AccessPointArn> </Filter> </MetricsConfiguration>
See Also
For more information about using this API in one of the language-specific Amazon SDKs, see the following: