All Products
Search

This Product

    Object Storage Service:PutBucketInventory

    Document Center

    Object Storage Service:PutBucketInventory

    Last Updated:Jun 11, 2026

    Use PutBucketInventory to configure an inventory rule for a bucket.

    Notes

    You can use an inventory to get information about objects in a bucket, such as the object count, size, storage class, and encryption status. When you configure inventory rules, note the following:

    • Before you configure an inventory rule, you must create a RAM role. This role requires permissions to read all objects from the source bucket and write objects to the destination bucket. We recommend using the OSS console to configure your first inventory rule, as the console helps you create a RAM role with the required permissions. For details on the permissions required for the RAM role, see bucket inventory.

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

    • The source and destination buckets for the exported inventory files must be in the same region.

    • To enable incremental inventory, contact technical support. This feature is supported only in the Mexico region.

    Permissions

    By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM policies or Bucket Policy.

    API

    Action

    Description

    PutBucketInventory

    oss:PutBucketInventory

    Configures inventories for a bucket.

    Request syntax

    Important

    • The 'inventoryId' query string parameter is required. Its value must match that of the 'Id' element in the request body.

    • You can use the LastModifyBeginTimeStamp, LastModifyEndTimeStamp, LowerSizeBound, UpperSizeBound, and StorageClass options only in the China (Qingdao), China (Hohhot), and Germany (Frankfurt) 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>
     <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>Monthly</Frequency>
        <DayOfMonth>1</DayOfMonth>
     </Schedule>
     <IncludedObjectVersions>All</IncludedObjectVersions>
     <OptionalFields>
        <Field>Size</Field>
        <Field>LastModifiedDate</Field>
        <Field>TransitionTime</Field>        
        <Field>ETag</Field>
        <Field>StorageClass</Field>
        <Field>IsMultipartUploaded</Field>
        <Field>EncryptionStatus</Field>
     </OptionalFields>
     <IncrementalInventory>
      <IsEnabled>true</IsEnabled>
      <Schedule>
        <Frequency>600</Frequency>
      </Schedule>
      <OptionalFields>
        <Field>SequenceNumber</Field>
        <Field>RecordType</Field>
        <Field>RecordTimestamp</Field>
        <Field>Requester</Field>
        <Field>RequestId</Field>
        <Field>SourceIp</Field>
        <Field>Size</Field>
        <Field>StorageClass</Field>
        <Field>LastModifiedDate</Field>
        <Field>ETag</Field>
        <Field>IsMultipartUploaded</Field>
        <Field>ObjectType</Field>
        <Field>ObjectAcl</Field>
        <Field>Crc64</Field>
        <Field>EncryptionStatus</Field>
      </OptionalFields>
    </IncrementalInventory>
  </InventoryConfiguration>

    Request elements

    Parameter

    Type

    Required

    Example

    Description

    Id

    String

    Yes

    report1

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

    • The name must be unique within the bucket.

    • The name cannot exceed 192 characters.

    IsEnabled

    Boolean

    Yes

    true

    Indicates whether the inventory is enabled.

    Valid values:

    • true: enables the inventory.

    • false: disables the inventory.

    Filter

    Container

    No

    N/A

    A container for the filter, which specifies the criteria for objects to include in the inventory.

    Prefix

    String

    No

    Pics/

    The prefix for filtering objects.

    Parent node: Filter

    LastModifyBeginTimeStamp

    String

    No

    1637883649

    The start of the last-modified time range for objects. The value is a UNIX timestamp in seconds.

    Value range: [1262275200, 253402271999]

    LastModifyEndTimeStamp

    String

    No

    1638347592

    The end of the last-modified time range for objects. The value is a UNIX timestamp in seconds.

    Value range: [1262275200, 253402271999]

    LowerSizeBound

    String

    No

    1024

    The minimum size (in bytes) of objects to include in the inventory.

    The value must be greater than or equal to 0 B and less than or equal to 48.8 TB.

    UpperSizeBound

    String

    No

    1048576

    The maximum size (in bytes) of objects to include in the inventory.

    The value must be greater than 0 B and less than or equal to 48.8 TB.

    StorageClass

    String

    No

    Standard,IA

    The storage classes of objects to include in the inventory. You can specify multiple storage classes.

    Valid values:

    • Standard

    • IA

    • Archive

    • ColdArchive

    • All (default): all storage classes

    Destination

    Container

    Yes

    N/A

    A container for information about the destination where inventory reports are stored.

    OSSBucketDestination

    Container

    Yes

    N/A

    A container for information about the bucket where inventory reports are stored.

    Parent node: Destination

    Format

    String

    Yes

    CSV

    The format of the inventory report. The report is a GZIP-compressed CSV file.

    Valid value: CSV

    Parent node: OSSBucketDestination

    AccountId

    String

    Yes

    100000000000000

    The ID of the Alibaba Cloud account that owns the destination bucket.

    Parent node: OSSBucketDestination

    RoleArn

    String

    Yes

    acs:ram::100000000000000:role/AliyunOSSRole

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

    Parent node: OSSBucketDestination

    Bucket

    String

    Yes

    acs:oss:::bucket_0001

    The destination bucket for the inventory report.

    Parent node: OSSBucketDestination

    Prefix

    String

    No

    prefix1/

    The prefix for the path where the inventory report files are stored.

    Parent node: OSSBucketDestination

    Encryption

    Container

    No

    N/A

    Container for the server-side encryption configuration of the inventory report.

    Valid values:

    • SSE-OSS: Use OSS-managed keys for encryption and decryption.

    • SSE-KMS: Use a default or specified customer master key (CMK) managed by Key Management Service (KMS) for encryption and decryption.

    Parent node: OSSBucketDestination

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

    SSE-OSS

    Container

    No

    N/A

    A container for the SSE-OSS encryption configuration.

    Parent node: Encryption

    SSE-KMS

    Container

    No

    N/A

    A container for the SSE-KMS encryption configuration.

    Parent node: Encryption

    KeyId

    String

    No

    keyId

    The ID of the CMK that is managed by KMS.

    Parent node: SSE-KMS

    Schedule

    Container

    Yes

    N/A

    A container for the schedule for generating the inventory report.

    Frequency

    String

    Yes

    Daily

    Specifies the frequency for generating the inventory report.

    Valid values:

    • Daily: Inventory reports are generated daily.

    • Weekly: Inventory reports are generated weekly.

    • Monthly: Inventory reports are generated monthly.

    • Once: An inventory report is generated only once.

    Important

    The Monthly schedule is not supported in the following regions: China (Zhangjiakou), China (Zhongwei), US (Virginia), US (Silicon Valley), Mexico, France (Paris),

    Parent node: Schedule

    DayOfMonth

    Positive integer

    No

    1

    If Frequency is set to Monthly, specifies the day of the month to generate the inventory. The value must be a positive integer from 1 to 31.

    • If you do not specify DayOfMonth, the inventory is generated at a fixed 30-day interval. The first scan starts on the day the rule is configured, and subsequent reports are generated every 30 days.

    • If the value is from 1 to 28, the inventory task starts on the specified day of each month.

    • If the value is from 29 to 31, the task starts on that day if the month has it. Otherwise, the task starts on the last day of the month. For example, if you set the value to 31, the task starts on April 30.

    Note

    This date specifies when the inventory task begins, not when the report is delivered. Because inventory generation is an asynchronous task whose duration depends on the object count, the report is delivered after this date.

    Parent node: Schedule

    AutoDelete

    Boolean

    No

    true

    Specifies whether to delete the inventory configuration after a one-time inventory is generated. This element is valid only when Frequency is set to Once.

    Valid values: true, false

    Parent node: Schedule

    IncludedObjectVersions

    String

    Yes

    All

    Specifies whether to include object versions in the inventory.

    Valid values:

    • All: Include all versions of the objects.

    • Current: Include only the current version of the objects.

    OptionalFields

    Container

    No

    N/A

    A container for the optional fields to include in the inventory report.

    Field

    String

    No

    Size

    The optional fields to include in the inventory report.

    • Key: The name of the object in the bucket. The name is URL-encoded.

    • VersionId: The version ID of the object. This field is included only if IncludedObjectVersions is set to All.

      • If versioning is not enabled for the bucket, this field is empty.

      • If versioning is enabled for the bucket, this field contains the version ID of the object.

    • IsDeleteMarker: Specifies whether the object version is a delete marker. This field is included only if IncludedObjectVersions is set to All.

      • If versioning is not enabled for the bucket, this field is set to false by default.

      • If versioning is enabled and the object is a delete marker, this field is set to true. If the object is not a delete marker, this field is set to false.

    • Size: The size of the object.

    • StorageClass: The storage class of the object.

    • TransitionTime: The time when the object was transitioned to the Archive or Cold Archive storage class by a lifecycle rule.

    • LastModifiedDate: The last modified time of the object.

    • ETag: The ETag of the object. The ETag is generated when an object is created and identifies the content of the object.

      • For an object created by using the PutObject operation, its ETag is the MD5 hash of the object content.

      • For an object created by using other methods, its ETag is a unique value calculated based on a specific rule and is not the MD5 hash of the object content.

    • IsMultipartUploaded: Specifies whether the object was uploaded by using a multipart upload.

    • ObjectType: The type of the object.

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

    • Crc64: The CRC-64 value of the object.

    • EncryptionStatus: Specifies whether the object is encrypted.

    • TaggingCount: The number of tags.

    IncrementalInventory

    Container

    No

    N/A

    A container for the incremental inventory configuration.

    IsEnabled

    Boolean

    Yes

    true

    Specifies whether to enable incremental inventory. Valid values:

    • true: Enables incremental inventory.

    • false: Disables incremental inventory.

    If this element is set to true, incremental inventory is enabled and takes effect even if InventoryConfiguration/IsEnabled is set to false.

    Parent node: IncrementalInventory

    Schedule

    Container

    Yes

    N/A

    A container for the schedule for generating the incremental inventory.

    Parent node: IncrementalInventory

    Frequency

    Positive integer

    Yes

    600

    The generation frequency for the incremental inventory, in seconds.

    The system uses a fixed frequency of 600 seconds. In each period, a directory prefix is automatically created, along with a corresponding manifest file and multiple CSV files generated during that period. Custom frequencies are not supported.

    Parent node: Schedule

    OptionalFields

    Container

    No

    N/A

    A container for the properties to include in the incremental inventory file.

    Parent node: IncrementalInventory

    Field

    String

    No

    Size

    The fields to include in the incremental inventory.

    Parent node: OptionalFields

    • SequenceNumber: A unique sequence number for each record. For records of the same object in the same bucket, you can sort them by SequenceNumber. The sorted records usually follow a chronological order.

    • RecordType: The event type. Valid values: CREATE, UPDATE_METADATA, and DELETE.

      • CREATE: Includes all upload methods for objects under the selected prefix, such as Put, Post, Append, MultipartUpload, and Copy.

      • UPDATE_METADATA: Includes all metadata updates for objects under the selected prefix.

      • DELETE: Includes all deletion methods for objects under the selected prefix, such as DeleteObject, DeleteMultipleObjects, generation of delete markers after versioning is enabled, and lifecycle-based deletion. Deletions include both delete markers and permanent deletions. For permanent deletion records, only the core fields Bucket, Key, SequenceNumber, RecordType, RecordTimestamp, and VersionId are retained; other columns are null.

    • RecordTimestamp: The record timestamp, in GMT, accurate to the millisecond. Example: "2024-08-25 18:08:01.024".

    • Requester: The Alibaba Cloud ID or principal ID of the requester.

    • RequestId: The unique identifier of the request.

    • SourceIp: The source IP address of the requester.

    • Key: The name of the object in the bucket. The name is URL-encoded.

    • VersionId: The version ID of the object. This field is included only if the inventory rule is configured to export all versions.

      • If versioning is not enabled for the bucket, this field is empty.

      • If versioning is enabled for the bucket, this field contains the version ID of the object.

    • IsDeleteMarker: Specifies whether the object version is a delete marker. This field is included only if the inventory rule is configured to export all versions.

      • If versioning is not enabled for the bucket, this field is set to false by default.

      • If versioning is enabled and the object is a delete marker, this field is set to true. If the object is not a delete marker, this field is set to false.

    • Size: The size of the object.

    • StorageClass: The storage class of the object.

    • LastModifiedDate: The last modified time of the object.

    • ETag: The ETag of the object. The ETag is generated when an object is created and identifies the content of the object.

      • For an object created by using the PutObject operation, its ETag is the MD5 hash of the object content.

      • For an object created by using other methods, its ETag is a unique value calculated based on a specific rule and is not the MD5 hash of the object content.

    • IsMultipartUploaded: Specifies whether the object was uploaded by using a multipart upload.

    • ObjectType: The type of the object.

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

    • Crc64: The CRC-64 value of the object.

    • EncryptionStatus: Specifies whether the object is encrypted.

    Response headers

    This interface returns only common response headers, e.g., Content-Length and Date. For details, see Common response headers.

    Examples

    Inventory configuration

    • 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>TransistionTime</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

    Monthly inventory configuration

    The following request configures an inventory to generate a report on the 3rd day of each month.

    • Sample request

        PUT /?inventory&inventoryId=monthly-report 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>monthly-report</Id>
     <IsEnabled>true</IsEnabled>
     <Filter>
         <Prefix>logs/</Prefix>
     </Filter>
     <Destination>
        <OSSBucketDestination>
          <Format>CSV</Format>
          <AccountId>100000000000000</AccountId>
          <RoleArn>acs:ram::100000000000000:role/AliyunOSSRole</RoleArn>
          <Bucket>acs:oss:::destbucket</Bucket>
          <Prefix>monthly-inventory/</Prefix>
        </OSSBucketDestination>
     </Destination>
     <Schedule>
        <Frequency>Monthly</Frequency>
        <DayOfMonth>3</DayOfMonth>
     </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

    One-time inventory configuration

    • Sample request

        PUT /?inventory&inventoryId=once-report 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>once-report</Id>
     <IsEnabled>true</IsEnabled>
     <Filter>
         <Prefix>log/</Prefix>
     </Filter>
     <Destination>
        <OSSBucketDestination>
          <Format>CSV</Format>
          <AccountId>100000000000000</AccountId>
          <RoleArn>acs:ram::100000000000000:role/AliyunOSSRole</RoleArn>
          <Bucket>acs:oss:::destbucket</Bucket>
          <Prefix>once-inventory/</Prefix>
        </OSSBucketDestination>
     </Destination>
     <Schedule>
        <Frequency>Once</Frequency>
        <AutoDelete>true</AutoDelete>
     </Schedule>
     <IncludedObjectVersions>All</IncludedObjectVersions>
     <OptionalFields>
        <Field>Size</Field>
        <Field>LastModifiedDate</Field>
        <Field>StorageClass</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

    Incremental inventory configuration

    • 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>Report-1</Id>
    <IsEnabled>true</IsEnabled>
    <Filter>
      <Prefix>test</Prefix>
    </Filter>
    <Destination>
      <OSSBucketDestination>
        <Format>CSV</Format>
        <AccountId>12xxxxxx29</AccountId>
        <RoleArn>acs:ram::12xxxxxx29:role/bucket-inventory-role</RoleArn>
        <Bucket>acs:oss:::test-inc-bi-bj</Bucket>
        <Prefix>Report-1</Prefix>
      </OSSBucketDestination>
    </Destination>
    <Schedule>
      <Frequency>Weekly</Frequency>
    </Schedule>
    <IncludedObjectVersions>All</IncludedObjectVersions>
    <OptionalFields>
      <Field>Size</Field>
      <Field>LastModifiedDate</Field>
      <Field>ETag</Field>
      <Field>StorageClass</Field>
    </OptionalFields>
    <IncrementalInventory>
      <IsEnabled>true</IsEnabled>
      <Schedule>
        <Frequency>600</Frequency>
      </Schedule>
      <OptionalFields>
        <Field>SequenceNumber</Field>
        <Field>RecordType</Field>
        <Field>RecordTimestamp</Field>
        <Field>Requester</Field>
        <Field>RequestId</Field>
        <Field>SourceIp</Field>
        <Field>Size</Field>
        <Field>StorageClass</Field>
        <Field>LastModifiedDate</Field>
        <Field>ETag</Field>
        <Field>IsMultipartUploaded</Field>
        <Field>ObjectType</Field>
        <Field>ObjectAcl</Field>
        <Field>Crc64</Field>
        <Field>EncryptionStatus</Field>
      </OptionalFields>
    </IncrementalInventory>
  </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

    SDK

    You can call this operation using the SDKs for the following languages:

    ossutil CLI

    The ossutil command for the PutBucketInventory operation is put-bucket-inventory.

    Error codes

    Error code

    HTTP status code

    Description

    InvalidArgument

    400

    One or more specified parameters are invalid.

    InventoryExceedLimit

    400

    The number of configured inventory rules exceeds the limit.

    AccessDenied

    403

    • Missing authentication credentials in the PutBucketInventory request.

    • You are not authorized to perform this operation.

    InventoryAlreadyExist

    409

    The inventory rule already exists.