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

GET Bucket Inventory

Description

This implementation of the GET operation returns an inventory configuration (identified by the inventory configuration ID) from the bucket.

To use this operation, you must have permissions to perform the s3:GetInventoryConfiguration action. The bucket owner has this permission by default and 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.

For information about the Amazon S3 inventory feature, see Amazon S3 Inventory in the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

GET /?inventory&id=inventory-configuration-ID HTTP/1.1 Host: bucketname.s3.amazonaws.com Date: date Authorization: authorization string (see Authenticating Requests (AWS Signature Version 4))

Request Parameters

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

Parameter Description Required
id

The ID that identifies the inventory configuration.

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

This implementation of the operation does not use request elements.

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

The Examples section shows an example of an inventory configuration XML. The following table describes the XML elements in the inventory configuration returned by the GET request.

Name Description
AccountId

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

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

Type: String

Ancestor: S3BucketDestination

Bucket

The Amazon Resource Name (ARN) of the bucket where inventory results are published.

Type: String

Ancestor: S3BucketDestination

Destination

Contains information about where to publish the inventory results.

Type: Container

Children: S3BucketDestination

Ancestor: InventoryConfiguration

Encryption

Contains the type of server-side encryption used to encrypt the inventory results.

Type: Container

Children: SSE-KMS, SSE-S3

Ancestor: S3BucketDestination

Field Contains the optional fields that are included in the inventory results. Multiple Field elements can be contained in OptionalFields.

Type: String

Ancestor: OptionalFields

Valid values: Size, LastModifiedDate, StorageClass, ETag, IsMultipartUploaded, ReplicationStatus, EncryptionStatus

Filter Specifies an inventory filter. The inventory only includes objects that meet the filter's criteria.

Type: Container

Children: Prefix

Ancestor: InventoryConfiguration

Format

Specifies the output format of the inventory results. Currently, Amazon S3 supports the comma-separated values (CSV) format and the Apache optimized row columnar (ORC) format.

Type: String

Ancestor: S3BucketDestination

Valid values: CSV, ORC

Frequency

Specifies how frequently inventory results are produced.

Type: String

Ancestor: Schedule

Valid values: Daily, or Weekly

Id

The ID that identifies the inventory configuration.

Type: String

Ancestor: InventoryConfiguration

IncludedObjectVersions

Object versions to include in the inventory list. If set to All, the list includes all the object versions, which adds the version-related fields VersionId, IsLatest, and DeleteMarker to the list. If set to Current, the list does not contain these version-related fields.

Type: String

Ancestor: InventoryConfiguration

Valid values: Current or All

InventoryConfiguration

Contains the inventory configuration.

Type: Container

Children: Id, IsEnabled, Filter, Destination, Schedule, IncludedObjectVersions, and OptionalFields elements.

Ancestor: None

IsEnabled

Specifies whether the inventory is enabled or disabled. If set to True, an inventory list is generated. If set to False, no inventory list is generated.

Type: String

Ancestor: InventoryConfiguration

Valid values: True or False

KeyId

The AWS KMS customer master key (CMK) used to encrypt the inventory file.

Type: String

Ancestor: SSE-KMS

Valid values: ARN of the CMK

OptionalFields

Contains the optional fields.

Type: Container

Children: Field

Ancestor: InventoryConfiguration

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

Type: String

Ancestor:Filter

Prefix

The prefix that is prepended to all inventory results.

Type: String

Ancestor: S3BucketDestination

Schedule

Contains the frequency of inventory results generation.

Type: Container

Children: Frequency

Ancestor: Destination.

SSE-KMS

Specifies to use server-side encryption with AWS KMS-managed keys (SSE-KMS) and contains the key that is used to encrypt the inventory file.

Type: Container

Children: KeyId

Ancestor: Encryption

SSE-S3

Specifies to use server-side encryption with Amazon S3-managed keys (SSE-S3) to encrypt the inventory file.

Type: Container

Ancestor: Encryption

Valid values: empty

S3BucketDestination

Contains the bucket ARN, file format, bucket owner (optional), prefix where inventory results are published (optional), and the type of server-side encryption that is used to encrypt the file (optional).

Type: Container

Children: Format, AccountId, Bucket, Prefix, Encryption

Ancestor: Destination.

Special Errors

This implementation of the operation does not return special errors. For general information about Amazon S3 errors and a list of error codes, see Error Responses.

Examples

Example: Configure an Inventory Report

The following GET request for the bucket examplebucket returns the inventory configuration with the ID list1.

GET /?inventory&id=list1 HTTP/1.1 Host: examplebucket.s3.amazonaws.com Date: Mon, 31 Oct 2016 12:00:00 GMT Authorization: authorization string

The following is a sample response.

HTTP/1.1 200 OK x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo x-amz-request-id: 236A8905248E5A02 Date: Mon, 31 Oct 2016 12:00:00 GMT Server: AmazonS3 Content-Length: length <?xml version="1.0" encoding="UTF-8"?> <InventoryConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Id>report1</Id> <IsEnabled>true</IsEnabled> <Destination> <S3BucketDestination> <Format>CSV</Format> <AccountId>123456789012</AccountId> <Bucket>arn:aws:s3:::destination-bucket</Bucket> <Prefix>prefix1</Prefix> <SSE-S3/> </S3BucketDestination> </Destination> <Schedule> <Frequency>Daily</Frequency> </Schedule> <Filter> <Prefix>myprefix/</Prefix> </Filter> <IncludedObjectVersions>All</IncludedObjectVersions> <OptionalFields> <Field>Size</Field> <Field>LastModifiedDate</Field> <Field>ETag</Field> <Field>StorageClass</Field> <Field>IsMultipartUploaded</Field> <Field>ReplicationStatus</Field> </OptionalFields> </InventoryConfiguration>