tencent cloud

Cloud Object Storage

DocumentationCloud Object StorageAPI DocumentationBucket APIsBucket inventory(inventory)Periodic InventoryPUT Bucket Inventory

PUT Bucket Inventory

PDF
Focus Mode
Font Size
Last updated: 2026-04-14 10:39:34

Feature Description

The PUT Bucket inventory API is used to create an inventory task in a bucket. After naming your inventory task, you can use this request to create it. For details, see Inventory feature overview.
Note:
COS allows you to create up to 1000 inventory tasks in each bucket.
Make sure that the account you are using has write permission to the target bucket so that COS can write the inventory task result files to the bucket.
When calling this API, ensure you have sufficient permissions to operate the inventory tasks for the bucket. The bucket owner has this permission by default. If you don't have this permission, request permissions for this operation from the bucket owner. For the authorization process, see Usage.
If you specify a prefix for inventory delivery, the COS backend will automatically append / after your specified prefix. For example, if you specify Prefix as the prefix, the inventory report path delivered by the COS backend will be Prefix/inventory_report.


Authorization Description

In the Authorization Policy, set the action to cos:PutBucketInventory. View all actions.

Request

Request Example

PUT /?inventory&id=inventory-configuration-ID HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Authorization: Auth String
Content-MD5: MD5
Note:
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com, where <BucketName-APPID> is the bucket name suffixed with APPID, such as examplebucket-1250000000. Refer to Bucket Overview > Basic Information and Bucket Overview > Bucket Naming Conventions; <Region> represents the COS region, see Regions and Access Endpoints.
Authorization: Auth String (For details, see Request Signature).

Request Parameters

To call the PUT Bucket inventory API, the inventory task name needs to be used. The format of this parameter is as follows:
Parameter
Description
Type
Required or Not
id
Inventory task name. Default value: None
Valid characters: a–z, A–Z, 0–9, -, _, .
String
Yes

Request Header

This API only uses common request headers. For details, see Common Request Headers.

Request Body

Set the specific configuration of the inventory task in the request body by using XML. The configuration includes the analysis objects, analysis frequency, analysis dimensions, and analysis result format and storage path of the inventory task. 
<InventoryConfiguration>
    <Id>list1</Id>
    <IsEnabled>true</IsEnabled>
    <Destination>
        <COSBucketDestination>
            <Format>CSV</Format>
            <AccountId>100000000001</AccountId>
            <Bucket>qcs::cos:ap-guangzhou::examplebucket-1250000000</Bucket>
            <Prefix>list1</Prefix>
            <Encryption>
                <SSE-COS></SSE-COS>
            </Encryption>
        </COSBucketDestination>
    </Destination>
    <Schedule>
        <Frequency>Daily|Weekly|Monthly</Frequency>
        <MonthlyDate></MonthlyDate>
    </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 detailed node descriptions are as follows:
Node Name
Parent Node
Description
Type
Required or Not
InventoryConfiguration
N/A
Inventory configuration parameters.
Container
Yes
Id
InventoryConfiguration
Name of the inventory, corresponding to the id parameter in the request.
String
Yes
IsEnabled
InventoryConfiguration
Identifier of whether the inventory is enabled.
If it is set to true, the inventory feature takes effect.
If it is set to false, no inventory is generated.
Boolean
Yes
IncludedObjectVersions
InventoryConfiguration
Whether to include the object version in the inventory.
If it is set to All, the inventory includes all object versions, and the VersionId, IsLatest, and DeleteMarker fields are added to the inventory.
If it is set to Current, the inventory does not include the object version information.
String
Yes
Filter
InventoryConfiguration
Filters out objects for analysis. The inventory feature analyzes objects that match the prefix set in Filter.
Container
No
And
Filter
If both the prefix and object tag conditions are required for filtering out objects to be analyzed, And is required.
Container
No
Prefix
And
Prefix of the object to be analyzed.
String
No
Tag
And
When objects for analysis are filtered out, one or more object tags can be used as filter conditions.
Container
No
Period
Filter
Creation time range of the objects to be analyzed.
Container
No
StartTime
Period
Start creation time of the objects to be analyzed. The parameter is a second-level timestamp, such as 1568688761.
String
No
EndTime
Period
End creation time of the objects to be analyzed. The parameter is a second-level timestamp, such as 1568688762.
String
No
OptionalFields
InventoryConfiguration
Analysis items that should be included in the inventory result.
Container
No
Field
OptionalFields
Names of optional analysis items in the inventory result. Optional fields include: Size, LastModifiedDate, StorageClass, ETag, IsMultipartUploaded, ReplicationStatus, Tag, Crc64, and x-cos-meta-*.
Note: If object tags are used in the filter conditions, tags should be added here.
In addition, users can enter custom headers in x-cos-meta-* format, such as x-cos-meta-testheader. The inventory outputs the corresponding object metadata. If the object does not contain that metadata, it is empty.
String
No
Schedule
InventoryConfiguration
Configures the inventory task period.
Container
Yes
Frequency
Schedule
Inventory task frequency. Options include: Daily, Weekly, or Monthly. With the monthly option, the specific inventory output date must be specified.
String
Yes
MonthlyDate
Schedule
If Monthly is specified, the specific inventory output date needs to be specified. The value range is 1 to 28.
Integer
No
Destination
InventoryConfiguration
Information about the inventory result destination.
Container
Yes
COSBucketDestination
Destination
Information about the bucket where the exported inventory results are stored.
Container
Yes
Bucket
COSBucketDestination
Name of the bucket where the inventory analysis results are stored.
String
Yes
AccountId
COSBucketDestination
The bucket owner's UIN (root account), such as 100000000001. This can be viewed in Account Information.
String
No
Prefix
COSBucketDestination
Prefix of the inventory analysis results.
String
No
Format
COSBucketDestination
File format of the inventory analysis results. An option is the CSV format.
String
Yes
Encryption
COSBucketDestination
Option for SSE of the inventory results.
Container
No
SSE-COS
Encryption
Encryption method of the COS-managed key, which does not need to be specified.
Container
No

Response

Response Headers

This API only returns common response headers. For details, see Common Response Headers.

Response Body

The response body of this request is empty.

Error Code

This API follows unified error responses and error codes. For details, see Error Codes.

Practical Case

Example 1: Adding an Inventory Task with an Object Prefix Specified

Request

This example adds an inventory task named list1 to the bucket examplebucket-1250000000.
The inventory task analyzes objects with the prefix myPrefix in the bucket and their versions.
The analysis frequency is once per day.
Analysis dimensions include Size, LastModifiedDate, StorageClass, ETag, IsMultipartUploaded, and ReplicationStatus.
The analysis results will be stored as CSV files in the bucket examplebucket-1250000000, with the prefix list1 and encrypted using SSE-COS.
PUT /?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=1503888878;1503889238&q-key-time=1503888878;1503889238&q-header-list=host&q-url-param-list=inventory&q-signature=****************************************
Content-MD5: AAq9nzrpsz5LJ4UEe1f6Q==
Host: examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com
Content-Length: 1024

<?xml version = "1.0" encoding = "UTF-8">
<InventoryConfiguration xmlns = "http://....">
    <Id>list1</Id>
    <IsEnabled>true</IsEnabled>
    <Destination>
        <COSBucketDestination>
            <Format>CSV</Format>
            <AccountId>100000000001</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>
        <Period>
            <StartTime>1568688761</StartTime>
            <EndTime>1568688762</EndTime>
        </Period>
    </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>

Response

After the above request, COS returns the following response, indicating that the inventory task list1 has been successfully set.
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Date: Mon, 28 Aug 2018 02:53:38 GMT
Server: tencent-cos
x-cos-request-id: NTlhMzg1ZWVfMjQ4OGY3MGFfMWE1NF8****

Example 2: Adding an Inventory Task with an Object Prefix and Object Tag Specified

Request

This example adds an inventory task named list2 to the bucket examplebucket-1250000000.
The inventory task analyzes objects with the prefix myPrefix and object tag {age:18} in the bucket and all their versions.
The analysis frequency is once per day.
Analysis dimensions include Size, LastModifiedDate, StorageClass, ETag, and Tag.
The analysis results are stored as a CSV file in the bucket inventorybucket-1250000000.
PUT /?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=1503888878;1503889238&q-key-time=1503888878;1503889238&q-header-list=host&q-url-param-list=inventory&q-signature=****************************************
Content-MD5: AAq9nzrpsz5LJ4UEe1f6Q==
Host: examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com
Content-Length: 1024

<?xml version = "1.0" encoding = "UTF-8">
<InventoryConfiguration xmlns = "http://....">
    <Id>list2</Id>
    <IsEnabled>true</IsEnabled>
    <Destination>
        <COSBucketDestination>
            <Format>CSV</Format>
            <AccountId>100000000001</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>

Response

After the above request, COS returns the following response, indicating that the inventory task list2 has been successfully set.
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Date: Mon, 28 Aug 2018 02:53:38 GMT
Server: tencent-cos
x-cos-request-id: NTlhMzg1ZWVfMjQ4OGY3MGFfMWE1NF8****

Example 3: Adding an Inventory Task to Export Custom Headers of an Object

Request

This example adds an inventory task named list3 to the bucket examplebucket-1250000000.
The inventory task analyzes objects with the prefix myPrefix and object tag {age:18} in the bucket and all their versions.
The analysis frequency is once per day.
Analysis dimensions include Size, LastModifiedDate, StorageClass, ETag, Tag, and x-cos-meta-myheader.
The analysis results are stored as a CSV file in the bucket inventorybucket-1250000000.
PUT /?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=1503888878;1503889238&q-key-time=1503888878;1503889238&q-header-list=host&q-url-param-list=inventory&q-signature=****************************************
Content-MD5: AAq9nzrpsz5LJ4UEe1f6Q==
Host: examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com
Content-Length: 1024

<?xml version = "1.0" encoding = "UTF-8">
<InventoryConfiguration xmlns = "http://....">
    <Id>list2</Id>
    <IsEnabled>true</IsEnabled>
    <Destination>
        <COSBucketDestination>
            <Format>CSV</Format>
            <AccountId>100000000001</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>
        <Field>Crc64</Field>
        <Field>x-cos-meta-myheader</Field>
    </OptionalFields>
</InventoryConfiguration>

Response

After the above request, COS returns the following response, indicating that the inventory task list3 has been successfully configured.
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Date: Mon, 28 Aug 2018 02:53:38 GMT
Server: tencent-cos
x-cos-request-id: NTlhMzg1ZWVfMjQ4OGY3MGFfMWE1NF8****

Previous Topic: DELETE BucketIntelligentTieringNext Topic: GET Bucket Inventory

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback