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

Obtaining a Specific Inventory of a Bucket

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 obtain a specific inventory of a bucket. For more information and constraints about bucket inventories, see Bucket Inventories.

Authorization Information

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 need to grant 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 need to grant 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 need to grant the obs:bucket:GetBucketInventoryConfiguration 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.

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

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 1 URI parameters

Parameter

Description

Mandatory

id

ID of the inventory configuration that you want to obtain.

Type: string

Specifications: A maximum of 64 characters

There is no default value.

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

Yes

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>

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

Table 2 lists elements contained in the response body.

Table 2 Response body parameters for a bucket inventory

Element

Description

InventoryConfiguration

Inventory configuration.

Type: container

Parent: none

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

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

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

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

Prefix

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

Type: string

Parent: Filter

Schedule

Time scheduled for generation of inventories.

Type: container

Parent: InventoryConfiguration

Child: Frequency

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

Destination

Destination bucket of an inventory.

Type: container

Parent: InventoryConfiguration

Format

Inventory format. Only the CSV format is supported.

Type: string

Parent: Destination

Value options: CSV

Bucket

Name of the bucket for saving inventories.

Type: string

Parent: Destination

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

IncludedObjectVersions

Indicates whether versions of objects are included in an inventory.

  • 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 include any version-related fields.

Type: string

Parent: InventoryConfiguration

Value options: All, Current

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

Field

Optional fields. The OptionalFields can contain multiple field elements.

Type: string

Parent: OptionalFields

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

Error Responses

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

Table 3 Error codes related to obtaining inventory configurations

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

References

  • 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