PUT Bucket Inventory¶
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 assign this permission to other users.
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>IsMultipartUploaded</Field>
<Field>ReplicationStatus</Field>
</OptionalFields>
</InventoryConfiguration>
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 about common request headers, see the section Common Request Headers.
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.
Element | Description | Mandatory |
|---|---|---|
InventoryConfiguration | Inventory configuration. Type: container Ancestor: none Children: 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 (_) Ancestor: 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 Valid values: true or false Ancestor: 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 Ancestor: InventoryConfiguration Children: Prefix | No |
Prefix | Filtering by name prefix. Only objects with the specified name prefix are included in the inventory. Type: string Ancestor: Filter | No |
Schedule | Time scheduled for generation of inventories. Type: container Ancestor: InventoryConfiguration Children: 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 Ancestor: Schedule Valid values: Daily or Weekly | Yes |
Destination | Destination bucket of an inventory. Type: container Ancestor: InventoryConfiguration | Yes |
Format | Inventory format. Only the CSV format is supported. Type: string Ancestor: Destination Valid values: CSV | Yes |
Bucket | Name of the bucket for saving inventories. Type: string Ancestor: 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 Ancestor: Destination | No |
IncludedObjectVersions | Indicates whether versions of objects are included in an inventory.
Type: string Ancestor: InventoryConfiguration Valid values: All or 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 Ancestor: InventoryConfiguration Children: Field | No |
Field | Optional fields. The OptionalFields can contain multiple field elements. Type: string Ancestor: OptionalFields Valid values: Size, LastModifiedDate, ETag, IsMultipartUploaded, ReplicationStatus. | No |
Response Syntax¶
HTTP/1.1 status_code
x-amz-request-id: request id
x-amz-id-2: id
Date: date
Content-Length: length
Response Headers¶
This response uses common headers. For details about common response headers, see the section Common Response Headers.
Response Elements¶
This response involves no elements.
Error Responses¶
In addition 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.
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: AWS 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>IsMultipartUploaded</Field>
<Field>ReplicationStatus</Field>
</OptionalFields>
</InventoryConfiguration>
Sample Response¶
HTTP/1.1 200 OK
Server: OBS
x-amz-request-id: 000001682C8545B0680893425D60AB83
x-amz-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSIGTuRtBfo7lpHSt0ZknhdDHmllwd/p
Date: Tue, 08 Jan 2019 08:12:38 GMT
Content-Length: 0