GetBucketMetricsConfiguration - Amazon Simple Storage Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

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: