Help Center/ Object Storage Service/ API Reference/ Bucket APIs/ Bucket Inventories/ Configuring Bucket Inventories
Updated on 2026-04-16 GMT+08:00
View PDF
Share

Configuring Bucket Inventories

Functions

The bucket inventory function periodically generates lists of metadata information of objects in a bucket. Inventories help you better understand object statuses in the bucket. You can call this API to configure bucket inventories. For more information and constraints about bucket inventories, see Bucket Inventories.

Constraints

Table 1 Constraints on bucket inventories

Item

Description

Bucket version

Inventories can be generated only for OBS 3.0 buckets, but the bucket that stores the inventory files can be any OBS version.

Maximum number of bucket inventories

A bucket can have a maximum of 10 inventories.

Source and destination buckets
  • The source bucket (for which a bucket inventory rule is configured) and the destination bucket (where the generated inventory files are stored) must belong to the same account.
  • The source and destination buckets must be in the same region.
  • The destination bucket cannot have server-side encryption enabled.

Functions
  • Inventory files must be in the CSV format.
  • Inventories can apply to all objects in a bucket or to a set of objects with the same name prefix.
  • The filter criteria of multiple inventory rules within the same bucket must not overlap.
    • If there is already an inventory rule for all objects in the bucket, any other inventory rule with an object name prefix specified cannot be created. To create a rule for only a set of objects, delete the inventory rule that applies to all objects first.
    • If there is already an inventory rule for a set of objects, a rule for all objects in the bucket cannot be created. To create a rule for all objects, delete all inventory rules that use a prefix filter.
    • Assume there is an inventory rule that uses the ab prefix as a filter. Any new inventory rule whose prefix overlaps with ab, such as a or abc, cannot be created. To create a rule with prefix a or abc, delete the overlapping rule first.
  • Only SSE-KMS can be used to encrypt bucket inventories.

Permissions

OBS must be authorized to upload inventory files to the destination bucket. The destination bucket needs a policy that grants OBS write permissions, with the Principal set to {"Service": "obs"}.

Others
  • The bucket inventory feature is not available to federated users.

Authorization Information

To call this API, you must be the bucket owner or have the permission to configure inventories for a bucket. You are advised to use IAM or bucket policies for authorization. For details about OBS authorization methods, see Differences Between OBS Permissions Control Methods.

  • If you use IAM for authorization, you need to use either role/policy-based authorization or identity policy-based authorization and configure the required permissions:
    • If you use role/policy-based authorization (IAM v3 APIs in the old IAM version), you need to grant the obs:bucket:PutBucketInventoryConfiguration permission. For details, see Creating a Custom IAM Policy.
    • If you use identity policy-based authorization (IAM v5 APIs in the new IAM version), you need to grant the obs:bucket:putBucketInventoryConfiguration permission, as shown in the following table. For details, see Creating a Custom IAM Identity Policy.

      Action

      Access Level

      Resource Type (*: Required)

      Condition Key

      Alias

      Dependencies

      obs:bucket:putBucketInventoryConfiguration

      Write

      bucket *

      -

      -

      -
      • obs:EpochTime
      • obs:SourceIp
      • obs:TlsVersion
      • obs:CustomDomain
  • If you use bucket policies for authorization, you need to grant the obs:bucket:PutBucketInventoryConfiguration permission. For details, see Creating a Custom Bucket Policy.

Request Syntax

The following is an example request. Replace BucketName with your bucket name and RegionID with the ID of the region where your bucket resides. You can obtain the region ID by referring to Supported Regions.

PUT /?inventory&id=configuration-id  HTTP/1.1
User-Agent: curl/7.29.0
Host: BucketName.obs.RegionID.myhuaweicloud.com 
Accept: */*
Date: GMT Date
Authorization: SignatureValue
Content-Length: BodyLength
Expect: 100-continue

<InventoryConfiguration>
   <Id>configuration-id</Id>
   <IsEnabled>true</IsEnabled>
   <Filter>
         <Prefix>inventoryTestPrefix</Prefix>
   </Filter>
   <Destination>
         <Format>CSV</Format>
         <Bucket>destbucket</Bucket>
         <Prefix>dest-prefix</Prefix>
   </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>ReplicationStatus</Field>
          <Field>EncryptionStatus</Field>
   </OptionalFields>
</InventoryConfiguration>

Description of the OBS request structure

  • An OBS request consists of the request method, request URI, request headers, and request body. The following figure shows an example of a request for creating a bucket. The bucket name is configured in the Host header, and the signature information is configured in the Authorization header. For details about how to calculate the signature, see Using an Authorization Header. For more information, see Constructing a Request.

URI Parameters

Table 2 URI parameters

Parameter

Type

Mandatory

Description

id

String

Yes

Definition

ID of the inventory configuration, which must be consistent with the inventory configuration ID in the message body.

Specifications: A maximum of 64 characters

Valid characters: letters, digits, hyphens (-), periods (.) and underscores (_)

Request Headers

This request uses common headers. For details, see Table 3.

Request Body

In this request, you must configure the bucket inventory in the request body. Upload the inventory configuration information in an XML file. Table 3 lists the configuration elements.

Table 3 Request body parameters for configuring a bucket inventory

Element

Description

Mandatory

InventoryConfiguration

Inventory configuration.

Type: container

Parent: none

Child: Id, IsEnabled, Filter, Destination, Schedule, IncludedObjectVersions, and OptionalFields

Yes

Id

ID of an inventory configuration, which must be consistent with the inventory configuration ID specified in the request.

Type: string

Specifications: A maximum of 64 characters

There is no default value.

Valid characters: letters, digits, hyphens (-), periods (.) and underscores (_)

Parent: InventoryConfiguration

Yes

IsEnabled

Indicates whether the rule is enabled. If this parameter is set to true, the inventory is generated. If not, the inventory will not be generated.

Type: boolean

Value options: true, false

Parent: InventoryConfiguration

Yes

Filter

Inventory filter configuration. The inventory contains only objects that meet the filter criteria (filtering by object name prefix). If no filter criteria are configured, all objects are included.

Type: container

Parent: InventoryConfiguration

Child: Prefix

No

Prefix

Filtering by name prefix. Only objects with the specified name prefix are included in the inventory.

Type: string

Parent: Filter

No

Schedule

Time scheduled for generation of inventories.

Type: container

Parent: InventoryConfiguration

Child: Frequency

Yes

Frequency

Intervals when inventories are generated. You can set this parameter to Daily or Weekly. An inventory is generated within one hour after it is configured for the first time. Then it is generated at the specified intervals.

Type: string

Parent: Schedule

Value options: Daily, Weekly

Yes

Destination

Destination bucket of an inventory.

Type: container

Parent: InventoryConfiguration

Yes

Format

Inventory format. Only the CSV format is supported.

Type: string

Parent: Destination

Value options: CSV

Yes

Bucket

Name of the bucket for saving inventories.

Type: string

Parent: Destination

Yes

Prefix

The name prefix of inventory files. If no prefix is configured, the names of inventory files will start with the BucketInventory by default.

Type: string

Parent: Destination

No

IncludedObjectVersions

Whether versions of objects are included in an inventory.

Type: string

Parent: InventoryConfiguration

Value options:

  • If this parameter is set to All, all the versions of objects are included in the inventory, and versioning related fields are added to the inventory, including: VersionId, IsLatest, and DeleteMarker.
  • If this parameter is set to Current, the inventory only lists information about the current object version and does not contain the VersionId, IsLatest, and DeleteMarker fields that are related to versioning.

Yes

OptionalFields

Extra metadata fields that can be added to an inventory. If this parameter is configured, fields specified in this parameter are contained in the inventory.

Type: container

Parent: InventoryConfiguration

Child: Field

No

Field

Optional fields. The OptionalFields can contain multiple field elements.

Type: string

Parent: OptionalFields

Value options: Size, LastModifiedDate, StorageClass, ETag, IsMultipartUploaded, ReplicationStatus, EncryptionStatus

No

Response Syntax

1
2
3
4
5
 
HTTP/1.1 status_code
x-obs-request-id: request id
x-obs-id-2: id
Date: date
Content-Length: length

Description of the OBS response structure

  • An OBS response consists of a response status code, response headers, and the response body. The following figure shows an example of a response for obtaining the bucket's ACL configuration.

Response Headers

This response uses common headers. For details, see Table 1.

Response Body

The response of this API does not contain a response body.

Error Responses

In addition to common error codes, this API also returns other error codes. The following lists some common errors and possible causes of this API. For details, see Table 4.

Table 4 Inventory configuration error codes

Error Code

Description

HTTP Status Code

MalformedXML

Incorrect XML format of the inventory.

400 Bad Request

InvalidArgument

Invalid parameter.

400 Bad Request

InventoryCountOverLimit

The number of inventories reached the upper limit.

400 Bad Request

PrefixExistInclusionRelationship

The prefix configured for this inventory overlaps with prefixes of existing inventories.

400 Bad Request

Sample Request

PUT /?inventory&id=test_id HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.com
Accept: */*
Date: Tue, 08 Jan 2019 08:17:10 +0000
Authorization: OBS UDSIAMSTUBTEST000001:/e2fqSfzLDb+0M36D4Op/s5KKr0=
Content-Length: 600
Expect: 100-continue

<InventoryConfiguration>
   <Id>test_id</Id>
   <IsEnabled>true</IsEnabled>
   <Filter>
         <Prefix>inventoryTestPrefix</Prefix>
   </Filter>
   <Destination>
         <Format>CSV</Format>
         <Bucket>destbucket</Bucket>
         <Prefix>dest-prefix</Prefix>
   </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>ReplicationStatus</Field>
          <Field>EncryptionStatus</Field>
   </OptionalFields>
</InventoryConfiguration>

Sample Response

1
2
3
4
5
6
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 000001682C8545B0680893425D60AB83
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSIGTuRtBfo7lpHSt0ZknhdDHmllwd/p
Date: Tue, 08 Jan 2019 08:12:38 GMT
Content-Length: 0

Using SDKs to Call APIs

You are advised to use OBS SDKs to call APIs. SDKs encapsulate APIs to simplify development. You can call SDK API functions to access OBS without manually calculating signatures.

Java

Python: not supported

C: not supported

Go: not supported

BrowserJS: not supported

.NET: not supported

Android: not supported

iOS: not supported

PHP: not supported

Node.js: not supported

References

  • For more information about configuring bucket inventories, see Bucket Inventories.
  • For details about the billing items involved in API operations, see Billing Items.
Parent Topic: Bucket Inventories