All Products
Search

This Product

    Object Storage Service:PutBucketInventory

    Document Center

    Object Storage Service:PutBucketInventory

    Last Updated:Nov 20, 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), 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>
     <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.