All Products
Search
Document Center

Object Storage Service:PutBucketInventory

Last Updated:Mar 01, 2024

Configures inventories for a bucket.

Usage notes

You can use an inventory to obtain information about objects in a bucket, such as the quantities, sizes, storage classes, and encryption status of the objects. When you configure an inventory for a bucket, take note of the following items:

  • Only the bucket owner or users that have the PutBucketInventory permission can initiate a PutBucketInventory request.

  • Before you configure an inventory for a bucket, you must create a RAM role. The RAM role must have the permissions to read all objects from the source bucket and write objects to the destination bucket. If you use the bucket inventory feature for the first time, we recommend that you configure an inventory in the Object Storage Service (OSS) console. After you configure the inventory, you can obtain the RAM role that has the permissions to perform all operations on OSS resources. For more information, see Bucket inventory.

  • You can configure up to 1,000 inventories for a bucket.

  • You must deploy the source bucket for which you want to configure an inventory in the same region as the destination bucket in which the inventory list is stored.

Request syntax

Important
  • The inventoryId parameter in the request header is required. The value of the inventoryId parameter must be the same as the value of the Id request parameter.

  • The LastModifyBeginTimeStamp, LastModifyEndTimeStamp, LowerSizeBound, UpperSizeBound, and StorageClass options are available only in the China (Qingdao), China (Hohhot), Germany (Frankfurt), and Australia (Sydney) regions.

  PUT /?inventory&inventoryId=report1 HTTP/1.1
  Host: BucketName.oss-cn-hangzhou.aliyuncs.com
  Date: Mon, 31 Oct 2016 12:00:00 GMT
  Authorization: authorization string
  Content-Length: length

  <?xml version="1.0" encoding="UTF-8"?>
    <InventoryConfiguration>
     <Id>report1</Id>
     <IsEnabled>true</IsEnabled>
     <Filter>
           <Prefix>filterPrefix/</Prefix>
           <LastModifyBeginTimeStamp>1637883649</LastModifyBeginTimeStamp>
           <LastModifyEndTimeStamp>1638347592</LastModifyEndTimeStamp>
           <LowerSizeBound>1024</LowerSizeBound>
           <UpperSizeBound>1048576</UpperSizeBound>
           <StorageClass>Standard,IA</StorageClass>
     </Filter>
     <Destination>
        <OSSBucketDestination>
           <Format>CSV</Format>
           <AccountId>1000000000000000</AccountId>
           <RoleArn>acs:ram::1000000000000000:role/AliyunOSSRole</RoleArn>
           <Bucket>acs:oss:::destination-bucket</Bucket>
           <Prefix>prefix1</Prefix>
           <Encryption>
              <SSE-KMS>
                 <KeyId>keyId</KeyId>
              </SSE-KMS>
           </Encryption>
        </OSSBucketDestination>
     </Destination>
     <Schedule>
        <Frequency>Daily</Frequency>
     </Schedule>
     <IncludedObjectVersions>All</IncludedObjectVersions>
     <OptionalFields>
        <Field>Size</Field>
        <Field>LastModifiedDate</Field>
        <Field>ETag</Field>
        <Field>StorageClass</Field>
        <Field>IsMultipartUploaded</Field>
        <Field>EncryptionStatus</Field>
     </OptionalFields>
  </InventoryConfiguration>

Request elements

Element

Type

Required

Example

Description

Id

String

Yes

report1

The name of the inventory. The name must meet the following requirements:

  • The name must be globally unique within the current bucket.

  • The name cannot exceed 192 characters in length.

IsEnabled

Boolean

Yes

true

Specifies whether to enable the bucket inventory feature.

Valid values:

  • true

  • false

Filter

Container

No

N/A

The container that stores the prefix used to filter objects. Only objects whose names contain the specified prefix are included in the inventory.

Prefix

String

No

Pics/

The prefix that is specified in the inventory.

Parent nodes: Filter

LastModifyBeginTimeStamp

String

No

1637883649

The beginning of the time range during which the object was last modified. Unit: seconds.

Valid values: [1262275200, 253402271999]

LastModifyEndTimeStamp

String

No

1638347592

The end of the time range during which the object was last modified. Unit: seconds.

Valid values: [1262275200, 253402271999]

LowerSizeBound

String

No

1024

The minimum size of the specified object. Unit: B.

Valid values: [0 B, 48.8 TB]

UpperSizeBound

String

No

1048576

The maximum size of the specified object. Unit: B.

Valid values: (0 B, 48.8 TB]

StorageClass

String

No

Standard,IA

The storage class of the object. You can specify multiple storage classes.

Valid values:

  • Standard

  • IA

  • Archive

  • ColdArchive

  • All

Destination

Container

Yes

N/A

The container that stores the exported inventory lists.

OSSBucketDestination

Container

Yes

N/A

The container that stores information about the bucket in which exported inventory lists are stored.

Parent nodes: Destination

Format

String

Yes

CSV

The format of exported inventory lists. The exported inventory lists are CSV objects compressed by using GZIP.

Valid value: CSV

Parent nodes: OSSBucketDestination

AccountId

String

Yes

100000000000000

The ID of the Alibaba Cloud account that is granted the permissions to call the PutBucketInventory operation by the bucket owner.

Parent nodes: OSSBucketDestination

RoleArn

String

Yes

acs:ram::100000000000000:role/AliyunOSSRole

The Alibaba Cloud Resource Name (ARN) of the role that has the permissions to read all objects from the source bucket and write objects to the destination bucket. Format: acs:ram::uid:role/rolename.

Parent nodes: OSSBucketDestination

Bucket

String

Yes

acs:oss:::bucket_0001

The name of the bucket in which exported inventory lists are stored.

Parent nodes: OSSBucketDestination

Prefix

String

No

prefix1/

The prefix of the path in which the exported inventory lists are stored.

Parent nodes: OSSBucketDestination

Encryption

Container

No

N/A

The container that stores the encryption method of the exported inventory lists.

Valid values:

  • SSE-OSS: OSS-managed keys are used to encrypt and decrypt inventory lists.

  • SSE-KMS: The default customer master key (CMK) or a specified CMK that is managed by Key Management Service (KMS) is used to encrypt and decrypt inventory lists.

Parent nodes: OSSBucketDestination

For more information, see Server-side encryption.

SSE-OSS

Container

No

N/A

The container that stores information about the SSE-OSS encryption method.

Parent nodes: Encryption

SSE-KMS

Container

No

N/A

The container that stores the CMK used for SSE-KMS encryption.

Parent nodes: Encryption

KeyId

String

No

keyId

The ID of the KMS-managed key.

Parent nodes: SSE-KMS

Schedule

Container

Yes

N/A

The container that stores information about the frequency at which inventory lists are exported.

Frequency

String

Yes

Daily

The frequency at which inventory lists are exported.

Valid values:

  • Daily: Inventory lists are exported on a daily basis.

  • Weekly: Inventory lists are exported on a weekly basis.

Parent nodes: Schedule

IncludedObjectVersions

String

Yes

All

Specifies whether to include the version information about the objects in inventory lists.

Valid values:

  • All: The information about all versions of the objects is exported.

  • Current: Only the information about the current versions of the objects is exported.

OptionalFields

Container

No

N/A

The container that stores the configuration fields in inventory lists.

Field

String

No

Size

The configuration fields that are included in inventory lists.

  • Size: the size of the object.

  • LastModifiedDate: the last modified time of the object.

  • ETag: the ETag of the object. The ETag identifies the content of the object.

  • StorageClass: the storage class of the object.

  • IsMultipartUploaded: specifies whether the object is uploaded by using multipart upload.

  • EncryptionStatus: the encryption status of the object.

  • ObjectAcl: the access control list (ACL) of the object.

  • TaggingCount: the number of tags.

  • ObjectType: the type of the object.

  • Crc64: the CRC-64 of the object.

Response headers

All headers in the response to a PutBucketInventory request are common response headers, such as Content-Length and Date. For more information, see Common response headers.

Examples

  • Sample request

      PUT /?inventory&inventoryId=report1 HTTP/1.1
      Host: oss-example.oss-cn-hangzhou.aliyuncs.com
      Date: Mon, 31 Oct 2016 12:00:00 GMT
      Authorization: authorization string
      Content-Length: length
    
      <?xml version="1.0" encoding="UTF-8"?>
      <InventoryConfiguration>
         <Id>report1</Id>
         <IsEnabled>true</IsEnabled>
         <Filter>
             <Prefix>Pics/</Prefix>
             <LastModifyBeginTimeStamp>1637883649</LastModifyBeginTimeStamp>
             <LastModifyEndTimeStamp>1638347592</LastModifyEndTimeStamp>
             <LowerSizeBound>1024</LowerSizeBound>
             <UpperSizeBound>1048576</UpperSizeBound>
             <StorageClass>Standard,IA</StorageClass>
         </Filter>
         <Destination>
            <OSSBucketDestination>
              <Format>CSV</Format>
              <AccountId>100000000000000</AccountId>
              <RoleArn>acs:ram::100000000000000:role/AliyunOSSRole</RoleArn>
              <Bucket>acs:oss:::destbucket</Bucket>
              <Prefix>prefix1/</Prefix>
              <Encryption>
                 <SSE-KMS>
                    <KeyId>keyId</KeyId>
                 </SSE-KMS>
               </Encryption>
            </OSSBucketDestination>
         </Destination>
         <Schedule>
            <Frequency>Daily</Frequency>
         </Schedule>
         <IncludedObjectVersions>All</IncludedObjectVersions>
         <OptionalFields>
            <Field>Size</Field>
            <Field>LastModifiedDate</Field>
            <Field>ETag</Field>
            <Field>StorageClass</Field>
            <Field>IsMultipartUploaded</Field>
            <Field>EncryptionStatus</Field>
         </OptionalFields>
      </InventoryConfiguration>
  • Sample response

      HTTP/1.1 200 OK
      x-oss-request-id: 56594298207FB3044385****
      Date: Mon, 31 Oct 2016 12:00:00 GMT
      Content-Length: 0
      Server: AliyunOSS

Error codes

Error code

HTTP status code

Description

InvalidArgument

400

One or more specified parameters are invalid.

InventoryExceedLimit

400

The number of configured inventories exceeds the limit.

AccessDenied

403

  • The authentication information is not included in the PutBucketInventory request.

  • You are not authorized to perform this operation.

InventoryAlreadyExist

409

The inventory that you want to configure already exists.