Use the inventory command to add, query, list, or delete inventory rules for a bucket - Object Storage Service

You can use the inventory feature to retrieve information about objects in a bucket, such as their quantity, size, storage class, and encryption status. To list many objects, use the inventory feature instead of the GetBucket (ListObjects) operation. This topic describes how to use the inventory command to add, query, list, or delete inventory rules for a bucket.

Precautions

You must have the oss:PutBucketInventory permission to add an inventory rule, the oss:GetBucketInventory permission to query an inventory rule, and the oss:DeleteBucketInventory permission to delete an inventory rule. For more information, see Attach a custom policy to a RAM user.
Starting with ossutil v1.6.16, you can use ossutil as the binary name in the command line for any operating system. If you use a version of ossutil earlier than 1.6.16, you must specify a binary name that corresponds to your operating system. For more information, see ossutil command reference.
For more information about the bucket inventory feature, see Bucket inventory.

Add an inventory rule

Follow these steps to add an inventory rule:

Create a Resource Access Management (RAM) role. The role must have permissions to read all objects in the source bucket and write files to the destination bucket. For more information about how to configure the role, see Create a RAM role for a trusted Alibaba Cloud service.
Create a local file and configure the inventory rule in XML format in the file.
ossutil reads the inventory configuration from the local file and then adds the configuration to the specified bucket.

Command syntax

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

The parameters are described as follows:

Parameter	Description
bucketname	The name of the bucket to which you want to add the inventory rule.
local_xml_file	The name of the local file that contains the inventory rule configuration. Example: `localfile.xml`.

Examples

Create a local file named localfile.xml and configure the inventory rule based on your scenario.

For example, you can create an inventory rule named inventorytest. This rule exports a weekly inventory report to a destination bucket named destbucket. The report lists all objects in the source bucket that match the `dir/` prefix and includes details such as the storage class, last modified time, and multipart upload status. The manifest file is encrypted using the AES256 encryption 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 add multiple inventory rules to a bucket. The rule name (ID) is the unique identifier of an inventory configuration. If you add a rule with an ID that already exists, a 409 error is returned.

Add an inventory rule to the examplebucket bucket.
```
ossutil inventory --method put oss://examplebucket localfile.xml
```
The following output indicates that the inventory rule is added.
```
0.299514(s) elapsed
```

Query a specific inventory rule

Command syntax

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

The parameters are described as follows:

Parameter	Description
bucketname	The name of the bucket whose inventory rule you want to query.
inventory_id	The name of the inventory rule.
local_xml_file	The name of the local file in which to store the inventory configuration. Example: `localfile.txt`. If you do not specify this parameter, the inventory configuration is printed to the screen.

Example
```
ossutil inventory --method get oss://examplebucket inventorytest localfile.txt
```
The following output indicates that the inventorytest rule for the examplebucket bucket is queried and the result is written to the localfile.txt file.
```
0.212407(s) elapsed
```

Query all inventory rules

Command syntax

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

The parameters are as follows:

Parameter	Description
bucketname	The name of the bucket whose inventory rules you want to obtain.
local_xml_file	The name of the local XML file in which to store the inventory configurations. If you do not specify this parameter, the inventory configurations are printed to the screen.
marker	The checklist filter condition generates a manifest file only for Objects that match the specified prefix. If left empty, a manifest file is generated for all Objects in the target Bucket.

Example
```
ossutil inventory --method list oss://examplebucket localfile.txt dest
```
The following output indicates that all inventory rules in the examplebucket bucket whose IDs start with the prefix `dest` are queried and the results are written to the localfile.txt file.
```
0.216897(s) elapsed
```

Delete a specific inventory rule

Command syntax

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

The parameters are described as follows:

Parameter	Description
bucketname	The name of the bucket from which you want to delete the inventory rule.
inventory_id	The name of the inventory rule.

Example
```
ossutil inventory --method delete oss://examplebucket inventorytest
```
The following output indicates that the inventorytest rule for the examplebucket bucket is deleted.
```
0.212407(s) elapsed
```

Common options

To access a bucket in a different region, use -e to specify the endpoint. To access a bucket owned by a different Alibaba Cloud account, use -i for the AccessKey ID and -k for the AccessKey secret.

For example, to add an inventory rule to a bucket named examplebucket that is in the China (Hangzhou) region and belongs to another Alibaba Cloud account, run the following command:

ossutil inventory --method put oss://examplebucket local_xml_file -e oss-cn-hangzhou.aliyuncs.com -i yourAccessKeyID  -k yourAccessKeySecret

Common options.