Configure a bucket inventory using ossutil put-bucket-inventory - Object Storage Service

Configures an inventory rule for a bucket.

The put-bucket-inventory command is the ossutil equivalent of the PutBucketInventory API operation.

Prerequisites

Before you begin, ensure that you have:

The oss:PutBucketInventory permission on the bucket, or bucket ownership
A Resource Access Management (RAM) role authorized to read all objects in the source bucket and write to the destination bucket

If this is your first time using bucket inventory, configure it through the OSS console first. The console creates the required RAM role automatically. For details, see Bucket inventory.

Usage notes

A bucket supports up to 1,000 inventory rules.
The destination bucket must be in the same region as the source bucket.
The incremental inventory feature requires access through Technical Support. It is currently available only in the Mexico region.

Syntax

ossutil api put-bucket-inventory --bucket <value> --inventory-id <value> --inventory-configuration <value> [flags]

Required parameters appear without brackets. Optional flags are listed in Command-line options.

Parameters

Parameter	Type	Description
`--bucket`	string	The name of the source bucket.
`--inventory-id`	string	The unique ID of the inventory rule.
`--inventory-configuration`	string	The inventory configuration. Accepts XML or JSON. If the value starts with `file://`, the configuration is loaded from the specified file.

--inventory-configuration schema

The --inventory-configuration parameter accepts the following structure.

Top-level fields:

Field	Type	Required	Description
`Id`	string	Yes	The inventory rule ID. Must match `--inventory-id`.
`IsEnabled`	boolean	Yes	Whether the rule is active. Valid values: `true`, `false`.
`Destination`	object	Yes	Specifies where to store inventory reports. See Destination fields below.
`Schedule`	object	Yes	Specifies the report generation frequency. See Schedule fields below.
`IncludedObjectVersions`	string	Yes	Which object versions to include. Valid value: `All`.
`Filter`	object	No	Filters the objects included in the inventory. See Filter fields below.
`OptionalFields`	object	No	Additional metadata fields to include in the report. See Optional fields for regular inventory below.
`IncrementalInventory`	object	No	Configures incremental inventory (restricted access). See IncrementalInventory fields below.

Destination fields:

The Destination object contains a single OSSBucketDestination object with the following fields:

Field	Type	Required	Description
`Format`	string	Yes	Output format. Valid value: `CSV`.
`AccountId`	string	Yes	Your Alibaba Cloud account ID.
`RoleArn`	string	Yes	The RAM role ARN. Format: `acs:ram::<AccountId>:role/<RoleName>`.
`Bucket`	string	Yes	The destination bucket. Format: `acs:oss:::<BucketName>`.
`Prefix`	string	No	The prefix for inventory report objects stored in the destination bucket.
`Encryption`	object	No	Encryption for inventory report objects. Specify either `SSE-OSS` (no additional fields) or `SSE-KMS` with a `KeyId` field.

Schedule fields:

Field	Type	Required	Description
`Frequency`	string	Yes	Report generation frequency. Valid values: `Daily`, `Weekly`.

Filter fields:

Field	Type	Required	Description
`Prefix`	string	No	Include only objects whose keys start with this prefix.
`LastModifyBeginTimeStamp`	integer	No	Include only objects last modified at or after this Unix timestamp.
`LastModifyEndTimeStamp`	integer	No	Include only objects last modified before this Unix timestamp.
`LowerSizeBound`	integer	No	Include only objects whose size in bytes is at or above this value.
`UpperSizeBound`	integer	No	Include only objects whose size in bytes is below this value.
`StorageClass`	string	No	Include only objects in the specified storage classes. Valid values: `Standard`, `IA`. Separate multiple values with a comma, for example, `Standard,IA`.

Optional fields for regular inventory:

The OptionalFields object contains a Field array. Each element must be one of:

Size, LastModifiedDate, ETag, StorageClass, IsMultipartUploaded, EncryptionStatus

IncrementalInventory fields:

Field	Type	Required	Description
`IsEnabled`	boolean	Yes	Whether incremental inventory is active. Valid values: `true`, `false`.
`Schedule.Frequency`	integer	Yes	Report generation interval in seconds. For example, `600` for every 10 minutes.
`OptionalFields.Field`	array	No	Additional metadata fields for incremental inventory reports. Valid values: `SequenceNumber`, `RecordType`, `RecordTimestamp`, `Requester`, `RequestId`, `SourceIp`, `Size`, `StorageClass`, `LastModifiedDate`, `ETag`, `IsMultipartUploaded`, `ObjectType`, `ObjectAcl`, `Crc64`, `EncryptionStatus`.

XML format:

<InventoryConfiguration>
  <Id>string</Id>                          <!-- Required: inventory rule ID -->
  <IsEnabled>true|false</IsEnabled>        <!-- Required: enable or disable the rule -->
  <Destination>
    <OSSBucketDestination>
      <Format>CSV</Format>                 <!-- Required: only CSV is supported -->
      <AccountId>string</AccountId>        <!-- Required: Alibaba Cloud account ID -->
      <RoleArn>string</RoleArn>            <!-- Required: RAM role ARN -->
      <Bucket>string</Bucket>              <!-- Required: acs:oss:::bucket-name format -->
      <Prefix>string</Prefix>              <!-- Optional: prefix for inventory report objects -->
      <Encryption>                         <!-- Optional: encryption for inventory report objects -->
        <SSE-OSS/>                         <!-- Option 1: OSS-managed encryption -->
        <SSE-KMS>                          <!-- Option 2: KMS-managed encryption -->
          <KeyId>string</KeyId>
        </SSE-KMS>
      </Encryption>
    </OSSBucketDestination>
  </Destination>
  <Schedule>
    <Frequency>Daily|Weekly</Frequency>    <!-- Required -->
  </Schedule>
  <Filter>                                 <!-- Optional: filter objects included in the inventory -->
    <Prefix>string</Prefix>
    <LastModifyBeginTimeStamp>integer</LastModifyBeginTimeStamp>
    <LastModifyEndTimeStamp>integer</LastModifyEndTimeStamp>
    <LowerSizeBound>integer</LowerSizeBound>
    <UpperSizeBound>integer</UpperSizeBound>
    <StorageClass>Standard|IA</StorageClass>
  </Filter>
  <IncludedObjectVersions>All</IncludedObjectVersions>  <!-- Required -->
  <OptionalFields>                         <!-- Optional: metadata fields to include in the report -->
    <Field>Size|LastModifiedDate|ETag|StorageClass|IsMultipartUploaded|EncryptionStatus</Field>
    ...
  </OptionalFields>
  <IncrementalInventory>                   <!-- Optional: incremental inventory (restricted access) -->
    <IsEnabled>true|false</IsEnabled>
    <Schedule>
      <Frequency>integer</Frequency>       <!-- Frequency in seconds, e.g., 600 -->
    </Schedule>
    <OptionalFields>
      <Field>SequenceNumber|RecordType|RecordTimestamp|Requester|RequestId|SourceIp|Size|StorageClass|LastModifiedDate|ETag|IsMultipartUploaded|ObjectType|ObjectAcl|Crc64|EncryptionStatus</Field>
      ...
    </OptionalFields>
  </IncrementalInventory>
</InventoryConfiguration>

JSON format:

{
  "Id": "string",
  "IsEnabled": true|false,
  "Destination": {
    "OSSBucketDestination": {
      "Format": "CSV",
      "AccountId": "string",
      "RoleArn": "string",
      "Bucket": "string",
      "Prefix": "string",
      "Encryption": {
        "SSE-OSS": {},
        "SSE-KMS": {
          "KeyId": "string"
        }
      }
    }
  },
  "Schedule": {
    "Frequency": "Daily"|"Weekly"
  },
  "Filter": {
    "Prefix": "string",
    "LastModifyBeginTimeStamp": integer,
    "LastModifyEndTimeStamp": integer,
    "LowerSizeBound": integer,
    "UpperSizeBound": integer,
    "StorageClass": "Standard"|"IA"|"Standard,IA"
  },
  "IncludedObjectVersions": "All",
  "OptionalFields": {
    "Field": [
      "Size"|"LastModifiedDate"|"ETag"|"StorageClass"|"IsMultipartUploaded"|"EncryptionStatus",
      ...
    ]
  },
  "IncrementalInventory": {
    "IsEnabled": true|false,
    "Schedule": {
      "Frequency": integer
    },
    "OptionalFields": {
      "Field": [
        "SequenceNumber"|"RecordType"|"RecordTimestamp"|"Requester"|"RequestId"|"SourceIp"|"Size"|"StorageClass"|"LastModifiedDate"|"ETag"|"IsMultipartUploaded"|"ObjectType"|"ObjectAcl"|"Crc64"|"EncryptionStatus",
        ...
      ]
    }
  }
}

Examples

Configure an inventory rule with filters and encryption

The following examples configure a daily inventory rule named report1 for examplebucket. The rule filters objects by prefix, size range, last-modified time, and storage class, and encrypts inventory reports with SSE-KMS.

Using an XML file (inventory-configuration.xml):

  <?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>

  ossutil api put-bucket-inventory --bucket examplebucket --inventory-id report1 --inventory-configuration file://inventory-configuration.xml

Using a JSON file (inventory-configuration.json):

  {
    "Id": "report1",
    "IsEnabled": "true",
    "Filter": {
      "Prefix": "Pics/",
      "LastModifyBeginTimeStamp": "1637883649",
      "LastModifyEndTimeStamp": "1638347592",
      "LowerSizeBound": "1024",
      "UpperSizeBound": "1048576",
      "StorageClass": "Standard,IA"
    },
    "Destination": {
      "OSSBucketDestination": {
        "Format": "CSV",
        "AccountId": "100000000000000",
        "RoleArn": "acs:ram::100000000000000:role/AliyunOSSRole",
        "Bucket": "acs:oss:::destbucket",
        "Prefix": "prefix1/",
        "Encryption": {
          "SSE-KMS": {
            "KeyId": "keyId"
          }
        }
      }
    },
    "Schedule": {
      "Frequency": "Daily"
    },
    "IncludedObjectVersions": "All",
    "OptionalFields": {
      "Field": [
        "Size",
        "LastModifiedDate",
        "ETag",
        "StorageClass",
        "IsMultipartUploaded",
        "EncryptionStatus"
      ]
    }
  }

  ossutil api put-bucket-inventory --bucket examplebucket --inventory-id report1 --inventory-configuration file://inventory-configuration.json

Using inline JSON:

  ossutil api put-bucket-inventory --bucket examplebucket --inventory-id report1 --inventory-configuration "{\"Id\":\"report1\",\"IsEnabled\":\"true\",\"Filter\":{\"Prefix\":\"Pics/\",\"LastModifyBeginTimeStamp\":\"1637883649\",\"LastModifyEndTimeStamp\":\"1638347592\",\"LowerSizeBound\":\"1024\",\"UpperSizeBound\":\"1048576\",\"StorageClass\":\"Standard,IA\"},\"Destination\":{\"OSSBucketDestination\":{\"Format\":\"CSV\",\"AccountId\":\"100000000000000\",\"RoleArn\":\"acs:ram::100000000000000:role/AliyunOSSRole\",\"Bucket\":\"acs:oss:::destbucket\",\"Prefix\":\"prefix1/\",\"Encryption\":{\"SSE-KMS\":{\"KeyId\":\"keyId\"}}}},\"Schedule\":{\"Frequency\":\"Daily\"},\"IncludedObjectVersions\":\"All\",\"OptionalFields\":{\"Field\":[\"Size\",\"LastModifiedDate\",\"ETag\",\"StorageClass\",\"IsMultipartUploaded\",\"EncryptionStatus\"]}}"

Configure an incremental inventory rule

Incremental inventory reports only object changes since the last run, rather than a full object listing. The following example enables both a weekly full inventory and a 10-minute incremental inventory for examplebucket.

Incremental inventory is currently available only in the Mexico region. Contact Technical Support to request access.

Using an XML file (inventory-configuration.xml):

  <?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>

  ossutil api put-bucket-inventory --bucket examplebucket --inventory-id report1 --inventory-configuration file://inventory-configuration.xml

Troubleshooting

Error	Likely cause	Resolution
403 Forbidden	Missing `oss:PutBucketInventory` permission, or the RAM role lacks access to the bucket	Grant the permission to the RAM user or role. See Bucket inventory.
InvalidArgument	Malformed `--inventory-configuration` value, unsupported field value, or exceeding 1,000 rules	Validate your JSON or XML against the schema above and check that enum values match exactly (for example, `Daily`, not `daily`).
Cross-region destination error	The destination bucket is in a different region than the source bucket	Use a destination bucket in the same region.

What's next

PutBucketInventory API reference — full API parameter reference
Bucket inventory — conceptual overview and console setup
Command-line options — global ossutil flags