Menu
Amazon Simple Storage Service
API Reference (API Version 2006-03-01)

PUT Bucket analytics

Description

This implementation of the PUT operation adds an analytics configuration (identified by the analytics ID) to the bucket. You can have up to 1,000 analytics configurations per bucket.

You can choose to have storage class analysis export analysis reports to a comma-separated values (CSV) flat file, see the DataExport request element. Reports are updated daily and are based on the object filters you configure. When selecting data export you specify a destination bucket and optional destination prefix where the file is written. You can export the data to a destination bucket in a different account. However, the destination bucket must be in the same region as the bucket that you are making the PUT analytics configuration to. For more information, see Amazon S3 Analytics – Storage Class Analysis in the Amazon Simple Storage Service Developer Guide.

Important

You must create a bucket policy on the destination bucket where the exported file is written to grant permissions to Amazon S3 to write objects to the bucket. For an example policy, see Granting Permissions for Amazon S3 Inventory and Storage Class Analysis.

To use this operation, you must have permissions to perform the s3:PutAnalyticsConfiguration 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 in the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

Copy
PUT /?analytics&id=configuration-ID HTTP/1.1 Host: bucketname.s3.amazonaws.com Content-Length: length Date: date Authorization: authorization string (see Authenticating Requests (AWS Signature Version 4)) Analytics configuration in the request body

Request Parameters

This implementation of PUT uses the parameter in the following table.

Parameter Description Required
id

The ID identifying the analytics configuration. This ID must match the request element id. Limited to 64 characters.

Type: String

Default: None

Valid Characters for id:  a-z A-Z 0-9 - _ .

Yes

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For more information, see Common Request Headers.

Request Elements

In the request, you must specify the analytics configuration in the request body, which is specified as XML. The Examples section shows an example of an analytics configuration.

The following table describes the XML elements in the analytics configuration:

Name Description Required
AnalyticsConfiguration

Contains the configuration and any analyses for the analytics filter.

Type: Container

Children: Id, Filter, StorageClassAnalysis

Ancestor: None

Yes
And A conjunction (logical AND) of predicates, which is used in evaluating an analytics filter. The operator must have at least two predicates.

Type: String

Children: Prefix, Tag

Ancestor: Filter

No
Bucket

The Amazon Resource Name (ARN) of the bucket where analytics results are published. This destination bucket must be in the same region as the bucket used for the analytics configuration PUT.

Type: String

Ancestor: S3BucketDestination

Yes
BucketAccountId

The ID of the account that owns the destination bucket where the analytics is published.

Although optional, we recommend that the value be set to prevent problems if the destination bucket ownership changes.

Type: String

Ancestor: S3BucketDestination

No
DataExport

A container used to describe how data related to the storage class analysis should be exported.

Type: Container

Children: OutputSchemaVersion, Destination

Ancestor: StorageClassAnalysis

No
Destination

Contains information about where to publish the analytics results.

Type: Container

Children: S3BucketDestination

Ancestor: DataExport

Yes
Filter Specifies an analytics filter. The analytics only includes objects that meet the filter's criteria. If no filter is speciified, all of the contents of the bucket are included in the analysis.

Type: Container

Children: And

Ancestor: AnalyticsConfiguration

No
Format

Specifies the output format of the analytics results. Currently, Amazon S3 supports the comma-separated value (CSV) format.

Type: String

Ancestor: S3BucketDestination

Valid values: CSV

Yes
Id

The ID that identifies the analytics configuration. This ID must match the request parameter id.

Type: String

Ancestor: AnalyticsConfiguration

Yes
Key

The key for a tag.

Type: String

Ancestor: Tag

Yes
OutputSchemaVersion

The version of the output schema to use when exporting data. Must be V_1.

Type: String

Ancestor: DataExport

Valid values: V_1

Yes
Prefix The prefix that an object must have to be included in the analytics results.

Type: String

Ancestor: And

No
Prefix

The prefix that is prepended to all analytics results.

Type: String

Ancestor: S3BucketDestination

No
StorageClassAnalysis

Indicates that data related to access patterns will be collected and made available to analyze the tradeoffs between different storage classes.

Type: Container

Children: DataExport

Ancestor: AnalyticsConfiguration

Yes
S3BucketDestination

Contains the bucket ARN, file format, bucket owner (optional), and prefix (optional) where analytics results are published.

Type: Container

Children: Format, BucketAccountId, Bucket, Prefix

Ancestor: Destination.

Yes
Tag

The tag to use when evaluating an analytics filter.

Type: Container

Children: Key, Value

Ancestor: And

No
Value

The value for a tag.

Type: String

Ancestor: Tag

Yes

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses. For more information, see Common Response Headers.

Response Elements

This implementation of the operation does not return response elements.

Special Errors

Amazon S3 checks the validity of the proposed AnalyticsConfiguration element and verifies whether the proposed configuration is valid when you call the PUT operation. The following table lists the errors and possible causes.

HTTP Error Code Cause
HTTP 400 Bad Request InvalidArgument

Invalid argument.

HTTP 403 Forbidden AccessDenied

You are not the owner of the specified bucket, or you do not have the s3:PutAnalyticsConfiguration bucket permission to set the configuration on the bucket.

For general information about Amazon S3 errors and a list of error codes, see Error Responses.

Examples

Example 1: Creating an Analytics Configuration

The following PUT request for the bucket examplebucket creates a new or replaces an existing analytics configuration with the ID report1. The configuration is defined in the request body.

Copy
PUT /?analytics&id=report1 HTTP/1.1 Host: examplebucket.s3.amazonaws.com Date: Mon, 31 Oct 2016 12:00:00 GMT Authorization: authorization string Content-Length: length <?xml version="1.0" encoding="UTF-8"?> <AnalyticsConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Id>report1</Id> <Filter> <And> <Prefix>images/</Prefix> <Tag> <Key>dog</Key> <Value>corgi</Value> </Tag> </And> </Filter> <StorageClassAnalysis> <DataExport> <OutputSchemaVersion>V_1</OutputSchemaVersion> <Destination> <S3BucketDestination> <Format>CSV</Format> <BucketAccountId>123456789012</BucketAccountId> <Bucket>arn:aws:s3:::destination-bucket</Bucket> <Prefix>destination-prefix</Prefix> </S3BucketDestination> </Destination> </DataExport> </StorageClassAnalysis> </AnalyticsConfiguration>

The following is a sample response.

Copy
HTTP/1.1 200 OK x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo x-amz-request-id: 236A8905248E5A01 Date: Mon, 31 Oct 2016 12:00:00 GMT Content-Length: 0 Server: AmazonS3