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


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

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

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 specified, 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 400 Bad Request`	TooManyConfigurations	You are attempting to create a new configuration but have already reached the 1,000-configuration limit.
`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.


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.


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

Document Conventions

« Previous Next »