All Products
Search
Document Center

Object Storage Service:inventory

Last Updated:Aug 14, 2024

You can use the bucket inventory feature to export information about specific objects in a bucket, such as the number, sizes, storage classes, and encryption state. To list a large number of objects, we recommend that you use the bucket inventory feature instead of the GetBucket (ListObjects) operation. This topic describes how to run the inventory command to create, query, list, or delete bucket inventories.

Usage notes

  • To create a bucket inventory, you must have the oss:PutBucketInventory permission. To query a bucket inventory, you must have the oss:GetBucketInventory permission. To delete a bucket inventory, you must have the oss:DeleteBucketInventory permission. For more information, see Attach a custom policy to a RAM user.

  • For ossutil 1.6.16 and later, you can directly use ossutil as the binary name in the command line. You do not need to update the binary name based on the operating system. For ossutil earlier than 1.6.16, you must specify a binary name that corresponds to the operating system. For more information, see ossutil command reference.

  • For more information about the bucket inventory feature, see Bucket inventory.

Create inventories

You can perform the following steps to create an inventory for a bucket:

  1. Create a Resource Access Management (RAM) role and authorize the role to read all objects in a source bucket and write objects to a destination bucket in which generated inventory lists are stored. For more information, see Create a RAM role for a trusted Alibaba Cloud service.

  2. Create a local file and configure inventories in the XML format in the file.

  3. Use ossutil to read the inventories from the local file and associate the inventories with the specified bucket.

  • Command syntax

    ossutil inventory --method put oss://bucketname local_xml_file

    The following table describes the preceding parameters.

    Parameter

    Description

    bucketname

    The name of the bucket for which you want to create inventories.

    local_xml_file

    The name of the local XML file in which you configure inventories. Example: localfile.xml.

  • Examples

    1. Create a local file named localfile.xml and configure inventories based on your requirements.

      The following example shows an inventory named inventorytest. Based on this inventory, Object Storage Service (OSS) exports the information about all objects whose names contain the dir/ prefix in the destbucket bucket on a weekly basis. The exported information includes the storage classes, last modified date, and multipart upload status of the objects. Exported inventory lists are encrypted by using the AES256 algorithm.

      <?xml version="1.0" encoding="UTF-8"?>
        <InventoryConfiguration>
            <Id>inventorytest</Id>
            <IsEnabled>true</IsEnabled>
            <Filter>
              <Prefix>dir/</Prefix>
            </Filter>
            <Destination>
                <OSSBucketDestination>
                    <Format>CSV</Format>
                    <AccountId>1746495857602745</AccountId>
                    <RoleArn>acs:ram::174649585760****:role/AliyunOSSRole</RoleArn>
                    <Bucket>acs:oss:::destbucket</Bucket>
                    <Encryption>
                        <SSE-OSS></SSE-OSS>
                    </Encryption>
                </OSSBucketDestination>
            </Destination>
            <Schedule>
                <Frequency>Weekly</Frequency>
            </Schedule>
            <IncludedObjectVersions>All</IncludedObjectVersions>
            <OptionalFields>
                <Field>LastModifiedDate</Field>
                <Field>StorageClass</Field>
                <Field>IsMultipartUploaded</Field>
                <Field>ETag</Field>
                <Field>EncryptionStatus</Field>
                <Field>Size</Field>
            </OptionalFields>
        </InventoryConfiguration>
      Important

      You can create multiple inventories for a bucket. The inventories are uniquely identified by their IDs. If the ID of the inventory that you want to create is the same as that of an existing inventory, HTTP status code 409 is returned.

    2. Create the inventory for a bucket named examplebucket.

      ossutil inventory --method put oss://examplebucket localfile.xml

      The following sample output indicates that the inventory is created.

      0.299514(s) elapsed

Query the specified inventory configured for a bucket

  • Command syntax

    ossutil inventory --method get oss://bucketname inventory_id [--local_xml_file ]

    The following table describes the preceding parameters.

    Parameter

    Description

    bucketname

    The name of the bucket whose inventory you want to query.

    inventory_id

    The name of the inventory that you want to query.

    local_xml_file

    The name of the local file in which you want to store the inventory. Example: localfile.txt. If this parameter is not specified, the inventory is displayed without being stored in a local file.

  • Examples

    ossutil inventory --method get oss://examplebucket inventorytest localfile.txt

    The following sample output indicates the inventorytest inventory configured for the examplebucket bucket is queried and written to the localfile.txt file:

    0.212407(s) elapsed

Query all inventories configured for a bucket

  • Command syntax

    ossutil inventory --method list oss://bucketname [--local_xml_file ] [--marker <value>]

    The following table describes the preceding parameters.

    Parameter

    Description

    bucketname

    The name of the bucket whose inventories you want to query.

    local_xml_file

    The name of the local XML file in which you want to store the inventories. If this parameter is not specified, the inventories are displayed without being stored in a local file.

    marker

    The prefix-based filtering condition for inventories. Inventory lists are generated only for objects whose names contain the specified prefix. If this parameter is not specified, inventory lists are generated for all objects in the bucket.

  • Examples

    ossutil inventory --method list oss://examplebucket localfile.txt dest

    The following sample output indicates that all inventories for objects whose names contain the dest prefix in the examplebucket bucket are queried and written to the localfile.txt file:

    0.216897(s) elapsed

Delete the specified inventory for a bucket

  • Command syntax

    ossutil inventory --method delete oss://bucketname inventory_id

    The following table describes the preceding parameters.

    Parameter

    Description

    bucketname

    The name of the bucket for which you want to delete the inventory.

    inventory_id

    The name of the inventory that you want to delete.

  • Examples

    ossutil inventory --method delete oss://examplebucket inventorytest

    The following sample output indicates that the system has deleted the inventorytest inventory that is configured for the examplebucket bucket.

    0.212407(s) elapsed

Common options

If you use ossutil to switch to a bucket that is located in another region, add the -e option to the command to specify the endpoint of the region in which the specified bucket is located. If you use ossutil to switch to a bucket that belongs to another Alibaba Cloud account, add the -i option to the command to specify the AccessKey ID of the specified account, and add the -k option to the command to specify the AccessKey secret of the specified account.

For example, you can run the following command to configure inventories for a bucket named examplebucket that is located in the China (Hangzhou) region and owned by another Alibaba Cloud account:

ossutil inventory --method put oss://examplebucket local_xml_file -e oss-cn-hangzhou.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA****  -k 67DLVBkH7EamOjy2W5RVAHUY9H****

For more information about common options, see Common options.