Configures inventories for a bucket.

Usage notes

You can use an inventory to obtain information about specific 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 on the bucket 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 permissions to read all objects from the source bucket and write objects to the destination bucket. For more information about the permissions of the RAM role for the bucket inventory feature, 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 parameters

ParameterTypeRequiredExampleDescription
IdStringYesreport1The name of the inventory. The name must be globally unique in the bucket.
IsEnabledBooleanYestrueSpecifies whether to enable the bucket inventory feature.
Valid values:
  • true: The bucket inventory feature is enabled.
  • false: The bucket inventory feature is disabled.
FilterContainerNoN/AThe container that stores the prefix used to filter objects. Only objects whose names contain the specified prefix are included in the inventory list.
PrefixStringNoPics/The prefix that is specified in the inventory.

Parent nodes: Filter

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

Valid values: [1262275200, 253402271999]

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

Valid values: [1262275200, 253402271999]

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

Valid values: [0 B, 48.8 TB]

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

Valid values: (0 B, 48.8 TB]

StorageClassStringNoStandard,IAThe storage class of the object. You can specify multiple storage classes.
Default value: All. Valid values:
  • Standard
  • Infrequent Access (IA)
  • Archive
  • Cold Archive
  • All
DestinationContainerYesN/AThe container that stores information about exported inventory lists.
OSSBucketDestinationContainerYesN/AThe container that stores information about the bucket in which exported inventory lists are stored.

Parent nodes: Destination

FormatStringYesCSVThe format of exported inventory lists. The exported inventory lists are comma-separated values (CSV) objects compressed by using GZIP. Set the value to CSV.

Valid value: CSV

Parent nodes: OSSBucketDestination

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

Parent nodes: OSSBucketDestination

RoleArnStringYesacs:ram::100000000000000:role/AliyunOSSRoleThe Alibaba Cloud Resource Name (ARN) of the role that has 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

BucketStringYesacs:oss:::bucket_0001The name of the bucket in which exported inventory lists are stored.

Parent nodes: OSSBucketDestination

PrefixStringNoprefix1/The prefix of the exported inventory lists.

Parent nodes: OSSBucketDestination

EncryptionContainerNoN/AThe container that stores the encryption method of exported inventory lists.

Valid values:

  • SSE-OSS: The SSE-OSS method is used to encrypt and decrypt inventory lists.
  • SSE-KMS: The default customer master key (CMK) or a specified CMK is used to encrypt and decrypt inventory lists.

Parent nodes: OSSBucketDestination

For more information about server-side encryption, see Server-side encryption.

SSE-OSSContainerNoN/AThe container that stores information about the SSE-OSS encryption method.

Parent nodes: Encryption

SSE-KMSContainerNoN/AThe container that stores the CMK used for SSE-KMS encryption.

Parent nodes: Encryption

KeyIdStringNokeyIdThe ID of the key that is managed by Key Management Service (KMS).

Parent nodes: SSE-KMS

ScheduleContainerYesN/AThe container that stores information about the frequency at which inventory lists are exported.
FrequencyStringYesDailyThe frequency at which the inventory list is exported.

Valid values:

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

Parent nodes: Schedule

IncludedObjectVersionsStringYesAllSpecifies whether to include the versioning information of 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.
OptionalFieldsContainerNoN/AThe container that stores the configuration fields included in inventory lists.
FieldStringNoSizeThe configuration fields included in inventory lists.
  • Size: the size of the object.
  • LastModifiedDate: the last modified time of the object.
  • ETag: the ETag value of the object, which is used to identify 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.

Response elements

The response headers that are included in this API operation contain only common response headers such as Content-Length and Date. For more information, see Common response headers.

Examples

  • Sample requests
      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 responses
      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 codeHTTP status codeDescription
InvalidArgument400The error message returned because the input parameter is invalid.
InventoryExceedLimit400The error message returned because the number of configured inventories has been reached.
AccessDenied403
  • The authentication information is not included in the PutBucketInventory request.
  • You are not authorized to perform this operation.
InventoryAlreadyExist409The error message returned because the inventory that you want to configure already exists.