Configures inventories for a bucket.
Usage notes
You can use an inventory to obtain information about objects in a bucket, such as the quantities, sizes, storage classes, and encryption status of the objects. When you configure an inventory for a bucket, take note of the following items:
Only the bucket owner or users that have the PutBucketInventory permission can initiate a PutBucketInventory request.
Before you configure an inventory for a bucket, you must create a RAM role. The RAM role must have the permissions to read all objects from the source bucket and write objects to the destination bucket. If you use the bucket inventory feature for the first time, we recommend that you configure an inventory in the Object Storage Service (OSS) console. After you configure the inventory, you can obtain the RAM role that has the permissions to perform all operations on OSS resources. For more information, see Bucket inventory.
You can configure up to 1,000 inventories for a bucket.
You must deploy the source bucket for which you want to configure an inventory in the same region as the destination bucket in which the inventory list is stored.
Request syntax
The inventoryId parameter in the request header is required. The value of the inventoryId parameter must be the same as the value of the Id request parameter.
The LastModifyBeginTimeStamp, LastModifyEndTimeStamp, LowerSizeBound, UpperSizeBound, and StorageClass options are available only in the China (Qingdao), China (Hohhot), Germany (Frankfurt), and Australia (Sydney) regions.
PUT /?inventory&inventoryId=report1 HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: Mon, 31 Oct 2016 12:00:00 GMT
Authorization: authorization string
Content-Length: length
<?xml version="1.0" encoding="UTF-8"?>
<InventoryConfiguration>
<Id>report1</Id>
<IsEnabled>true</IsEnabled>
<Filter>
<Prefix>filterPrefix/</Prefix>
<LastModifyBeginTimeStamp>1637883649</LastModifyBeginTimeStamp>
<LastModifyEndTimeStamp>1638347592</LastModifyEndTimeStamp>
<LowerSizeBound>1024</LowerSizeBound>
<UpperSizeBound>1048576</UpperSizeBound>
<StorageClass>Standard,IA</StorageClass>
</Filter>
<Destination>
<OSSBucketDestination>
<Format>CSV</Format>
<AccountId>1000000000000000</AccountId>
<RoleArn>acs:ram::1000000000000000:role/AliyunOSSRole</RoleArn>
<Bucket>acs:oss:::destination-bucket</Bucket>
<Prefix>prefix1</Prefix>
<Encryption>
<SSE-KMS>
<KeyId>keyId</KeyId>
</SSE-KMS>
</Encryption>
</OSSBucketDestination>
</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>EncryptionStatus</Field>
</OptionalFields>
</InventoryConfiguration>
Request elements
Element | Type | Required | Example | Description |
Id | String | Yes | report1 | The name of the inventory. The name must meet the following requirements:
|
IsEnabled | Boolean | Yes | true | Specifies whether to enable the bucket inventory feature. Valid values:
|
Filter | Container | No | N/A | The container that stores the prefix used to filter objects. Only objects whose names contain the specified prefix are included in the inventory. |
Prefix | String | No | Pics/ | The prefix that is specified in the inventory. Parent nodes: Filter |
LastModifyBeginTimeStamp | String | No | 1637883649 | The beginning of the time range during which the object was last modified. Unit: seconds. Valid values: [1262275200, 253402271999] |
LastModifyEndTimeStamp | String | No | 1638347592 | The end of the time range during which the object was last modified. Unit: seconds. Valid values: [1262275200, 253402271999] |
LowerSizeBound | String | No | 1024 | The minimum size of the specified object. Unit: B. Valid values: [0 B, 48.8 TB] |
UpperSizeBound | String | No | 1048576 | The maximum size of the specified object. Unit: B. Valid values: (0 B, 48.8 TB] |
StorageClass | String | No | Standard,IA | The storage class of the object. You can specify multiple storage classes. Valid values:
|
Destination | Container | Yes | N/A | The container that stores the exported inventory lists. |
OSSBucketDestination | Container | Yes | N/A | The container that stores information about the bucket in which exported inventory lists are stored. Parent nodes: Destination |
Format | String | Yes | CSV | The format of exported inventory lists. The exported inventory lists are CSV objects compressed by using GZIP. Valid value: CSV Parent nodes: OSSBucketDestination |
AccountId | String | Yes | 100000000000000 | The ID of the Alibaba Cloud account that is granted the permissions to call the PutBucketInventory operation by the bucket owner. Parent nodes: OSSBucketDestination |
RoleArn | String | Yes | acs:ram::100000000000000:role/AliyunOSSRole | The Alibaba Cloud Resource Name (ARN) of the role that has the permissions to read all objects from the source bucket and write objects to the destination bucket. Format: Parent nodes: OSSBucketDestination |
Bucket | String | Yes | acs:oss:::bucket_0001 | The name of the bucket in which exported inventory lists are stored. Parent nodes: OSSBucketDestination |
Prefix | String | No | prefix1/ | The prefix of the path in which the exported inventory lists are stored. Parent nodes: OSSBucketDestination |
Encryption | Container | No | N/A | The container that stores the encryption method of the exported inventory lists. Valid values:
Parent nodes: OSSBucketDestination For more information, see Server-side encryption. |
SSE-OSS | Container | No | N/A | The container that stores information about the SSE-OSS encryption method. Parent nodes: Encryption |
SSE-KMS | Container | No | N/A | The container that stores the CMK used for SSE-KMS encryption. Parent nodes: Encryption |
KeyId | String | No | keyId | The ID of the KMS-managed key. Parent nodes: SSE-KMS |
Schedule | Container | Yes | N/A | The container that stores information about the frequency at which inventory lists are exported. |
Frequency | String | Yes | Daily | The frequency at which inventory lists are exported. Valid values:
Parent nodes: Schedule |
IncludedObjectVersions | String | Yes | All | Specifies whether to include the version information about the objects in inventory lists. Valid values:
|
OptionalFields | Container | No | N/A | The container that stores the configuration fields in inventory lists. |
Field | String | No | Size | The configuration fields that are included in inventory lists.
|
Response headers
All headers in the response to a PutBucketInventory request are common response headers, such as Content-Length and Date. For more information, see Common response headers.
Examples
Sample request
PUT /?inventory&inventoryId=report1 HTTP/1.1 Host: oss-example.oss-cn-hangzhou.aliyuncs.com Date: Mon, 31 Oct 2016 12:00:00 GMT Authorization: authorization string Content-Length: length <?xml version="1.0" encoding="UTF-8"?> <InventoryConfiguration> <Id>report1</Id> <IsEnabled>true</IsEnabled> <Filter> <Prefix>Pics/</Prefix> <LastModifyBeginTimeStamp>1637883649</LastModifyBeginTimeStamp> <LastModifyEndTimeStamp>1638347592</LastModifyEndTimeStamp> <LowerSizeBound>1024</LowerSizeBound> <UpperSizeBound>1048576</UpperSizeBound> <StorageClass>Standard,IA</StorageClass> </Filter> <Destination> <OSSBucketDestination> <Format>CSV</Format> <AccountId>100000000000000</AccountId> <RoleArn>acs:ram::100000000000000:role/AliyunOSSRole</RoleArn> <Bucket>acs:oss:::destbucket</Bucket> <Prefix>prefix1/</Prefix> <Encryption> <SSE-KMS> <KeyId>keyId</KeyId> </SSE-KMS> </Encryption> </OSSBucketDestination> </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>EncryptionStatus</Field> </OptionalFields> </InventoryConfiguration>
Sample response
HTTP/1.1 200 OK x-oss-request-id: 56594298207FB3044385**** Date: Mon, 31 Oct 2016 12:00:00 GMT Content-Length: 0 Server: AliyunOSS
Error codes
Error code | HTTP status code | Description |
InvalidArgument | 400 | One or more specified parameters are invalid. |
InventoryExceedLimit | 400 | The number of configured inventories exceeds the limit. |
AccessDenied | 403 |
|
InventoryAlreadyExist | 409 | The inventory that you want to configure already exists. |