Tenant Cloud Storage Cloud Object Storage API References Setting an Inventory Task

Setting an Inventory Task

Last Updated At: 2025-10-21 09:10:00

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.
  • You should write a bucket policy to the destination bucket for COS to write the result files of the inventory tasks to the bucket.
  • To call this API, ensure that you have the necessary permission for inventory tasks in the bucket. The bucket owner has this permission by default. If you do not have it, you should apply for it from the bucket owner first.
  • If you specify a prefix for inventory delivery, the COS backend automatically adds / after the prefix you specified. If you specify Prefix as the prefix, the path of the inventory report delivered by the COS backend is Prefix/inventory_report.

Authorization Description

In the authorization policy, action is set to cos:PutBucketInventory.

Request

Request Example 

PUT /?inventory&id=inventory-configuration-ID HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: GMT Date
Authorization: Auth String
Content-MD5: MD5

Description

Authorization: Auth String (For details, refer to 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
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 documentation.

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:region1::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>

Specific node descriptions are as follows:

Node Name Parent Node Description Type Required
InventoryConfiguration No Inventory configuration parameters. Container Yes
Id InventoryConfiguration Name of the inventory, corresponding to the id parameter in the request. Container 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.		 String 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 period. Options include Daily, Weekly, or Monthly. Enumerated values: Daily, Weekly. If Monthly is specified, the specific inventory output date needs to 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 UIN (root account) of the bucket owner, for example, 100000000001. 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 the public response header. For details, see Common Response Headers documentation.

Response Body

The response body for this request is empty.

Error Code

This API follows unified error response and error codes. For details, please refer to the Error Codes document.

Practical Case

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

Request

This example adds the inventory task 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 are stored as a CSV file in the bucket examplebucket-1250000000. The file has the prefix list1 and is encrypted by 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=AKIDZfbOAo7cllgPvF9cXFrJD0a1ICvR****&q-sign-time=1503888878;1503889238&q-key-time=1503888878;1503889238&q-header-list=host&q-url-param-list=inventory&q-signature=254bf9cd3d6615e89a36ab652437f9d45c5f****
Content-MD5: AAq9nzrpsz5LJ4UEe1f6Q==
Host: examplebucket-1250000000.cos.city.yfm4.fsphere.cn
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:region1::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 receiving the preceding request, COS returns the following response, indicating that the inventory task list1 is set successfully.

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Date: Mon, 28 Aug 2018 02:53:38 GMT
x-cos-request-id: NTlhMzg1ZWVfMjQ4OGY3MGFfMWE1NF8****

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

Request

This example adds the inventory task 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=AKIDZfbOAo7cllgPvF9cXFrJD0a1ICvR****&q-sign-time=1503888878;1503889238&q-key-time=1503888878;1503889238&q-header-list=host&q-url-param-list=inventory&q-signature=254bf9cd3d6615e89a36ab652437f9d45c5f****
Content-MD5: AAq9nzrpsz5LJ4UEe1f6Q==
Host: examplebucket-1250000000.cos.city.yfm4.fsphere.cn
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:region1::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 receiving the preceding request, COS returns the following response, indicating that the inventory task list2 is set successfully.

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Date: Mon, 28 Aug 2018 02:53:38 GMT
x-cos-request-id: NTlhMzg1ZWVfMjQ4OGY3MGFfMWE1NF8****

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

Request

This example adds the inventory task 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=AKIDZfbOAo7cllgPvF9cXFrJD0a1ICvR****&q-sign-time=1503888878;1503889238&q-key-time=1503888878;1503889238&q-header-list=host&q-url-param-list=inventory&q-signature=254bf9cd3d6615e89a36ab652437f9d45c5f****
Content-MD5: AAq9nzrpsz5LJ4UEe1f6Q==
Host: examplebucket-1250000000.cos.city.yfm4.fsphere.cn
Content-Length: 1024

<?xml version = "1.0" encoding = "UTF-8">
<InventoryConfiguration xmlns = "http://....">
    <Id>list3</Id>
    <IsEnabled>true</IsEnabled>
    <Destination>
        <COSBucketDestination>
            <Format>CSV</Format>
            <AccountId>100000000001</AccountId>
            <Bucket>qcs::cos:region1::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 receiving the preceding request, COS returns the following response, indicating that the inventory task list3 is set successfully.

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Date: Mon, 28 Aug 2018 02:53:38 GMT
x-cos-request-id: NTlhMzg1ZWVfMjQ4OGY3MGFfMWE1NF8****