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

Querying an Inventory Task

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

Description

The GET Bucket inventory API is used to query the inventory task information of a user in a bucket. When initiating this request, the user should provide the inventory task name and obtain a request signature to indicate that the request is authorized. For detailed inventory features, see Inventory feature overview.

Note

  • 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:GetBucketInventory.

Request

Request Example 

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

Description

Authorization: Auth String (For details, refer to Request Signature).

Request Parameters

To call the GET Bucket inventory API, the inventory task name is required. 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

The request body of this request is empty.

Response

Response Headers

This API only returns the public response header. For details, see Common Response Headers documentation.

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

Specific node descriptions are as follows:

Node Name Parent Node Description Type
InventoryConfiguration No Inventory configuration parameters. Container
Id InventoryConfiguration Name of the inventory, corresponding to the id parameter in the request. Container
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
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
Filter InventoryConfiguration Filters out objects for analysis. The inventory feature analyzes objects that match the prefix set in Filter. Container
And Filter If both the prefix and object tag conditions are required for filtering out objects to be analyzed, And is required. Container
Prefix And Prefix of the object to be analyzed. String
Tag And When objects for analysis are filtered out, one or more object tags can be used as filter conditions. Container
Period Filter Creation time range of the objects to be analyzed. Container
StartTime Period Start creation time of the objects to be analyzed. The parameter is a second-level timestamp, such as 1568688761. String
EndTime Period End creation time of the objects to be analyzed. The parameter is a second-level timestamp, such as 1568688762. String
OptionalFields InventoryConfiguration Analysis dimensions that should be included in the inventory results. Container
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
Schedule InventoryConfiguration Configures the inventory task period. Container
Frequency Schedule Inventory task period. Options include By day and By week. String
Destination InventoryConfiguration Information about the inventory result destination. Container
COSBucketDestination Destination Information about the bucket where the exported inventory results are stored. Container
Bucket COSBucketDestination Name of the bucket where the inventory analysis results are stored. String
AccountId COSBucketDestination ID of the bucket owner. String
Prefix COSBucketDestination Prefix of the inventory analysis results. String
Format COSBucketDestination File format of the inventory analysis results. Options include CSV and ORC. String
Encryption COSBucketDestination Option for SSE of the inventory results. Container
SSE-COS Encryption Encryption method of the COS-managed key. Container

Error Code

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

Practical Case

Example 1: Obtaining the Configuration of an Inventory Task for Obtaining Objects with a Specified Object Prefix

Request

The following example queries the list1 inventory job configuration of the examplebucket-1250000000.

GET /?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=1503895278;1503895638&q-key-time=1503895278;1503895638&q-header-list=host&q-url-param-list=inventory&q-signature=f77900be432072b16afd8222b4b349aabd83****
Host: examplebucket-1250000000.cos.city.yfm4.fsphere.cn

Response

After receiving the request, COS returns the following response, indicating that the inventory task list1 in the bucket is enabled.

  • The inventory task analyzes objects with the prefix myPrefix in the bucket examplebucket-1250000000 and all their versions.
  • The analysis frequency is once per day.
  • Analysis dimensions include Size, LastModifiedDate, StorageClass, ETag, IsMultipartUploaded, and ReplicationStatus.
  • Analysis results are stored as a CSV file in the bucket examplebucket-1250000000. The file has a prefix list1 and is encrypted by using SSE-COS.
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 331
Date: Mon, 28 Aug 2018 02:53:39 GMT
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:city::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 the Configuration of an Inventory Task for Obtaining Objects with a Specified Object Prefix and Object Tag

Request

The following example queries the list2 inventory job configuration of the examplebucket-1250000000.

GET /?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=1503895278;1503895638&q-key-time=1503895278;1503895638&q-header-list=host&q-url-param-list=inventory&q-signature=f77900be432072b16afd8222b4b349aabd83****
Host: examplebucket-1250000000.cos.city.yfm4.fsphere.cn

Response

After receiving the request, COS returns the following response, indicating that the inventory task list2 in the bucket is enabled.

  • The inventory task analyzes objects with the prefix myPrefix, and object tag {age:18} in the bucket examplebucket-1250000000 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.
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 331
Date: Mon, 28 Aug 2018 02:53:39 GMT

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