Run the inventory command to create, delete, or query bucket inventories - Object Storage Service

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:

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.
Create a local file and configure inventories in the XML format in the file.
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

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.

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.