Overview
This API is used to query an inventory job of a bucket. When calling this API, you need to specify the inventory job ID and carry a request signature. For more information, please see Inventory Overview. Note:
To call this API, ensure that you have the necessary permission on the bucket inventory job.
The bucket owner has such permission by default. If you do not have the permission, you can request it from the bucket owner.
If you specify a prefix for the destination path of the inventory report, COS will automatically append a slash (/) to the specified prefix. For example, if you set the prefix to Prefix, COS will deliver the inventory report to Prefix/inventory_report.
Authorization Description
In the authorization policy, set action to cos:GetBucketInventory. View all actions. Request
Sample request
GET /?inventory&id=inventory-configuration-ID HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Authorization: Auth String
Request parameters
To call GET Bucket inventory, specify the following parameter:
|
| ID of the inventory job. Default value: None Letters, digits, hyphens (-), underscores (_), and dots (.) are supported. | | |
Request body
The request body of this request is empty.
Response
Response body
The response body returns application/xml data. The following contains all the nodes:
<InventoryConfiguration>
<Id>list1</Id>
<IsEnabled>true</IsEnabled>
<Destination>
<COSBucketDestination>
<Format>CSV</Format>
<AccountId>1250000000</AccountId>
<Bucket>qcs::cos:ap-guangzhou::examplebucket-1250000000</Bucket>
<Prefix>list1</Prefix>
<Encryption>
<SSE-COS></SSE-COS>
</Encryption>
</COSBucketDestination>
</Destination>
<Schedule>
<Frequency>Daily</Frequency>
</Schedule>
<Filter>
<Prefix>myPrefix</Prefix>
</Filter>
<IncludedObjectVersions>All</IncludedObjectVersions>
<OptionalFields>
<Field>Size</Field>
<Field>LastModifiedDate</Field>
<Field>ETag</Field>
<Field>StorageClass</Field>
<Field>IsMultipartUploaded</Field>
<Field>ReplicationStatus</Field>
<Field>Tag</Field>
<Field>Crc64</Field>
<Field>x-cos-meta-*</Field>
</OptionalFields>
</InventoryConfiguration>
The nodes are described as follows:
|
| | This contains configuration parameters of the inventory | |
| | Inventory ID, corresponding to the request parameter Id | |
| | Whether the inventory is enabled true: Yes
false: No (no inventory will be generated.)
| |
| | Whether object versions are included in the inventory All: Yes (the inventory includes all object versions and the additional fields VersionId, IsLatest, and DeleteMarker.)
Current: No
| |
| | Filters objects prefixed with the specified value to analyze. | |
| | When you filter the objects to analyze, if both conditions Prefix and Tag are required, use the And container. | |
| | Prefix of the objects to analyze | |
| | When you filter the objects to analyze, you can use one or multiple object tags as a filter condition. | |
| | Creation time range of the objects to analyze | |
| | Creation start time of the objects to analyze. The parameter is a timestamp in seconds, for example, 1568688761. | |
| | Creation end time of the objects to analyze. The parameter is a timestamp in seconds, for example, 1568688762. | |
| | Analysis dimensions to include in the inventory result | |
| | Optional analysis items to include in the inventory result. The optional fields include Size, LastModifiedDate, StorageClass, ETag, IsMultipartUploaded, ReplicationStatus, Tag, Crc64, and x-cos-meta-*. Note that if Tag is used as a filter condition, the Tag field must be included in the inventory result. In addition, custom headers in the format of x-cos-meta-* are supported, for example, x-cos-meta-testheader. If such a custom header is entered, the corresponding object metadata will be output in the inventory. If the object does not include the metadata, the field is null. | |
| | | |
| | Frequency of the inventory job, which can be Daily, Weekly or Monthly | |
| | Information about the inventory result destination | |
| | Information about the bucket that stores the exported inventory result | |
| | | |
| | | |
| | Prefix of the inventory result | |
| | Format of the inventory result. Valid values: CSV, ORC | |
| | Server-side encryption for the inventory result | |
| | Encryption with COS-managed key | |
Error codes
This API returns common error responses and error codes. For more information, see Error Codes. Examples
Example 1: Obtaining an inventory job with a specified object prefix
Request
The following example queries the list1 inventory job configuration of the examplebucket-1250000000 bucket:
GET /?inventory&id=list1 HTTP/1.1
Date: Mon, 28 Aug 2018 02:53:38 GMT
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1503895278;1503895638&q-key-time=1503895278;1503895638&q-header-list=host&q-url-param-list=inventory&q-signature=****************************************
Host: examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com
Response
After the request above is made, COS returns the following response, indicating that the inventory job list1 is currently enabled in the bucket:
Objects to analyze: objects prefixed with myPrefix and all their versions in the examplebucket-1250000000 bucket
Analysis frequency: daily
Analysis dimensions: Size, LastModifiedDate, StorageClass, ETag, IsMultipartUploaded, and ReplicationStatus
Analysis result: to be stored in the examplebucket-1250000000 bucket as a CSV file, which is prefixed with list1 and encrypted with SSE-COS.
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 331
Date: Mon, 28 Aug 2018 02:53:39 GMT
Server: tencent-cos
x-cos-request-id: NTlhMzg1ZWVfMjQ4OGY3MGFfMWE1NF84Y2M
<?xml version = "1.0" encoding = "UTF-8">
<InventoryConfiguration xmlns = "http://....">
<Id>list1</Id>
<IsEnabled>true</IsEnabled>
<Destination>
<COSBucketDestination>
<Format>CSV</Format>
<AccountId>1250000000</AccountId>
<Bucket>qcs::cos:ap-guangzhou::examplebucket-1250000000</Bucket>
<Prefix>list1</Prefix>
<Encryption>
<SSE-COS></SSE-COS>
</Encryption>
</COSBucketDestination>
</Destination>
<Schedule>
<Frequency>Daily</Frequency>
</Schedule>
<Filter>
<Prefix>myPrefix</Prefix>
</Filter>
<IncludedObjectVersions>All</IncludedObjectVersions>
<OptionalFields>
<Field>Size</Field>
<Field>LastModifiedDate</Field>
<Field>ETag</Field>
<Field>StorageClass</Field>
<Field>IsMultipartUploaded</Field>
<Field>ReplicationStatus</Field>
</OptionalFields>
</InventoryConfiguration>
Example 2: Obtaining an inventory job with a specified object prefix and object tag
Request
The following example queries the list2 inventory job configuration of the examplebucket-1250000000 bucket:
GET /?inventory&id=list2 HTTP/1.1
Date: Mon, 28 Aug 2018 02:53:38 GMT
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1503895278;1503895638&q-key-time=1503895278;1503895638&q-header-list=host&q-url-param-list=inventory&q-signature=****************************************
Host: examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com
Response
After the request above is made, COS returns the following response indicating that the inventory job list2 is currently enabled in the bucket.
Objects to analyze: objects prefixed with myPrefix and tagged with {age:18} and all their versions in the examplebucket-1250000000 bucket
Analysis frequency: daily
Analysis dimensions: Size, LastModifiedDate, StorageClass, ETag, and Tag
The result will be stored in the inventorybucket-1250000000 bucket as a CSV file.
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 331
Date: Mon, 28 Aug 2018 02:53:39 GMT
Server: tencent-cos
x-cos-request-id: NTlhMzg1ZWVfMjQ4OGY3MGFfMWE1NF84Y2M
<?xml version = "1.0" encoding = "UTF-8">
<InventoryConfiguration xmlns = "http://....">
<Id>list2</Id>
<IsEnabled>true</IsEnabled>
<Destination>
<COSBucketDestination>
<Format>CSV</Format>
<AccountId>1250000000</AccountId>
<Bucket>qcs::cos:ap-guangzhou::inventorybucket-1250000000</Bucket>
</COSBucketDestination>
</Destination>
<Schedule>
<Frequency>Daily</Frequency>
</Schedule>
<Filter>
<And>
<Prefix>myPrefix</Prefix>
<Tag>
<Key>age</Key>
<Value>18</Value>
</Tag>
</And>
</Filter>
<IncludedObjectVersions>All</IncludedObjectVersions>
<OptionalFields>
<Field>Size</Field>
<Field>LastModifiedDate</Field>
<Field>StorageClass</Field>
<Field>ETag</Field>
<Field>Tag</Field>
</OptionalFields>
</InventoryConfiguration>