Help Center/ Object Storage Service/ API Reference/ Bucket APIs/ Bucket Inventories/ Obtaining a Specific Bucket Inventory
Updated on 2026-07-27 GMT+08:00
View PDF
Share

Obtaining a Specific Bucket Inventory

Function

The bucket inventory function periodically generates a list of object metadata information for a bucket, helping you better understand object statuses in the bucket. You can call this API to obtain a specific bucket inventory. For more information and constraints about bucket inventories, see Bucket Inventories.

Authorization

To call this API, you must be the bucket owner or have the permission to obtain the inventory configuration of 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 must have the obs:bucket:GetBucketInventoryConfiguration 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 must have the obs:bucket:getBucketInventoryConfiguration 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:getBucketInventoryConfiguration

      Read

      bucket *

      -

      -

      -
      • obs:EpochTime
      • obs:SourceIp
      • obs:TlsVersion
      • obs:CustomDomain
  • If you use bucket policies for authorization, you must have the obs:bucket:GetBucketInventoryConfiguration permission. For details, see Creating a Custom Bucket Policy.

URI

GET /

Calling Method

For details, see Calling APIs. Before calling this API, calculate the API signature and add it to the request.

You can debug this API in API Explorer.

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.

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

URI Parameters

Table 1 URI parameters

Parameter

Mandatory

Type

Description

inventory

Yes

String

Definition

An identifier that marks this API as related to bucket inventory.

Constraints

When calculating the signature, add /BucketName/?inventory to CanonicalizedResource. For details, see Using an Authorization Header.

Range

inventory

Default Value

N/A

id

Yes

String

Definition

ID of the inventory configuration that you want to obtain.

Constraints

N/A

Range

The value can contain a maximum of 64 bytes, including letters (a–z and A–Z), digits (0–9), hyphens (-), underscores (_), and periods (.).

Default Value

N/A

Request Headers

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

Request Body

This request contains no request body parameters.

Response Syntax

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
 
HTTP/1.1 status_code
Server: OBS
x-obs-request-id: request id
x-obs-id-2: id
Content-Type: application/xml
Date: date
Content-Length: length

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<InventoryConfiguration  xmlns="http://obs.region.myhuaweicloud.com/doc/2015-06-30/">
  <Id>configuration-id</Id>
  <IsEnabled>true</IsEnabled>
  <Destination>
    <Format>CSV</Format>
    <Bucket>destbucket</Bucket>
    <Prefix>prefix</Prefix>
  </Destination>
  <Schedule>
    <Frequency>Daily</Frequency>
  </Schedule>
  <IncludedObjectVersions>Current</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>

Response Headers

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

Response Body

Table 2 lists elements contained in the response body.

Table 2 Response body parameters for a bucket inventory

Element

Type

Description

InventoryConfiguration

Container

Definition

Inventory configuration. InventoryConfiguration is the parent node of Id, IsEnabled, Filter, Destination, Schedule, IncludedObjectVersions, and OptionalFields.

Range

N/A

Id

String

Definition

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

Range

The value can contain a maximum of 64 bytes, including letters (a–z and A–Z), digits (0–9), hyphens (-), underscores (_), and periods (.).

IsEnabled

Boolean

Definition

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

Parent: InventoryConfiguration

Range

  • true: Inventory files will be generated.
  • false: Inventory files will not be generated.

Filter

Container

Definition

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

Parent: InventoryConfiguration

Range

N/A

Prefix

String

Definition

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

Parent: Filter

Range

The value can contain a maximum of 1,024 characters.

Schedule

Container

Definition

Time scheduled for generation of inventory files.

Parent: InventoryConfiguration

Range

N/A

Frequency

String

Definition

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

Parent: Schedule

Range

  • Daily: Inventory files are generated once a day.
  • Weekly: Inventory files are generated once a week.

Destination

Container

Definition

Destination configuration of an inventory.

Parent: InventoryConfiguration

Range

N/A

Format

String

Definition

Inventory file format. Only the CSV format is supported.

Parent: Destination

Range

The value can only be CSV.

Bucket

String

Definition

Name of the bucket for storing inventory files.

Parent: Destination

Range

N/A

Prefix

String

Definition

Name prefix for inventory files. If no prefix is configured, the inventory file names will start with the BucketInventory prefix by default.

Parent: Destination

Range

The value can contain a maximum of 254 characters and cannot contain the following special characters: \*?"<>|

IncludedObjectVersions

String

Definition

Whether the inventory files contain object versioning information.

Parent: InventoryConfiguration

Range

  • All: Versioning related fields including VersionId, IsLatest, and DeleteMarker will appear in inventory files, and information about all object versions will be included.
  • Current: Versioning related fields including VersionId, IsLatest, and DeleteMarker will not appear in inventory files, and only information about the current object version will be included.

OptionalFields

Container

Definition

Additional object metadata fields that can be included in inventory files.

Parent: InventoryConfiguration

Range

N/A

Field

String

Definition

An optional field. An OptionalFields can contain multiple field elements. You can add additional object metadata fields.

Parent: OptionalFields

Range

  • Size: object size.
  • LastModifiedDate: time when the object was created.
  • ETag: object ETag.
  • StorageClass: object storage class.
  • IsMultipartUploaded: whether it is a multipart upload object. The value can be true or false.
  • ReplicationStatus: replication status of a CRR object.
  • EncryptionStatus: server-side encryption method.
  • BucketKeyStatus: key status, which can be ENABLED or DISABLED.
  • UserMeta: user-defined metadata.
  • CRC64: CRC64 check on the data content.
  • ObjectType: object type.

Error Responses

In addition to common error codes, this API also returns some special error codes. Table 3 lists the special error codes and their possible causes.

Table 3 Special errors for obtaining a bucket inventory

Error Code

Description

HTTP Status Code

NoSuchInventoryConfiguration

No inventory configuration found matching the specified ID.

404 Not Found

Sample Request

GET /?inventory&id=id1 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.com
Accept: */*
Date: Tue, 08 Jan 2019 09:32:24 +0000
Authorization: OBS UDSIAMSTUBTEST000001:ySWncC9M08jNsyXdJLSMJkpi7XM=

Sample Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 000001682CB4C2EE6808A0D8DF9F3D00
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSBjn5O7Jv9CqvUMO0BenehRdil1n8rR
Content-Type: application/xml
Date: Tue, 08 Jan 2019 09:04:30 GMT
Content-Length: 626

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<InventoryConfiguration  xmlns="http://obs.region.myhuaweicloud.com/doc/2015-06-30/">
  <Id>id1</Id>
  <IsEnabled>true</IsEnabled>
  <Destination>
    <Format>CSV</Format>
    <Bucket>bucket</Bucket>
    <Prefix>prefix</Prefix>
  </Destination>
  <Schedule>
    <Frequency>Daily</Frequency>
  </Schedule>
  <IncludedObjectVersions>Current</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>

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

Harmony: not supported

Helpful Links

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