Configuring Bucket Inventories

Functions

OBS uses the PUT method to configure bucket inventories. Each bucket can have a maximum of 10 inventories.

To perform this operation, ensure that you have the PutBucketInventoryConfiguration permission. By default, the bucket owner has this permission and can grant it to others.

Request Syntax

PUT /?inventory&id=configuration-id  HTTP/1.1
User-Agent: curl/7.29.0
Host: bucketname.obs.region.example.com
Accept: */*
Date: date
Authorization: authorization string
Content-Length: length
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>

Request Parameters

**Table 1** Request parameters
Parameter	Description	Mandatory
id	ID of the inventory configuration, which must be consistent with the inventory configuration ID in the message body. 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 Elements

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

**Table 2** Bucket inventory configuration elements
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 is 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	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 contains only the current objects versions at the time when the inventory is generated. No versioning fields are displayed in the inventory. Type: string Parent: InventoryConfiguration Value options: All, Current	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

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

Response Headers

The response to the request uses common headers. For details, see Table 1.

Response Elements

This response contains no elements.

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 3.

**Table 3** 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.example.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

    
         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