Creating a One-time Inventory Task

Description

The POST Bucket inventory API is used to create a one-time inventory task for a bucket. Unlike an inventory task created by using the PUT Bucket inventory API, an inventory task created by using this API starts immediately after creation, and each task is executed only once instead of being executed periodically. This feature allows you to flexibly obtain the list of objects in the bucket, ensuring more refined object management.

Note

• 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. For example, if you specify Prefix as the prefix, the path of inventory report delivered by the COS backend is Prefix/inventory_report.
• If you submit another inventory task with the same ID as the ongoing inventory task or a periodic inventory task, the server returns a duplicate inventory task error.

Request

Request Example

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

Description

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

Request Parameters

To call the POST Bucket inventory API, the inventory task name is required. The format of this parameter is as follows:

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 using XML in the request body. An example is as follows:

Note

• The one-time inventory job cannot include IsEnabled or Schedule parameter.
• Other parameters are the same as those in PUT Bucket inventory.
• The storage path of the one-time inventory report is the same as that of the periodic inventory report. For details, see Inventory Report Storage Path.

<InventoryConfiguration>
    <Id>inventory-id</Id>
    <Destination>
        <COSBucketDestination>
            <Format>CSV</Format>
            <AccountId>100000000001</AccountId>
            <Bucket>qcs::cos:city::examplebucket-1250000000</Bucket>
            <Prefix>cos_bucket_inventory</Prefix>
            <Encryption>
                <SSE-COS></SSE-COS>
            </Encryption>
        </COSBucketDestination>
    </Destination>
    <Filter>
        <And>
            <Prefix>myPrefix</Prefix>
            <Tag>
                <Key>string</Key>
                <Value>string</Value>
            </Tag>
        </And>
    </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>

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: Filtering by the Specified Prefix to Generate a One-time Inventory

Request

This example initiates the inventory task disposable in the bucket examplebucket-1250000000.

• The inventory task analyzes objects with the prefix myPrefix and object tag {age:18} in the bucket and their versions.
• The analysis dimensions include Size, LastModifiedDate, StorageClass, ETag, and Tag.
• The analysis results are stored as a CSV file in the bucket inventorybucket-1250000000.
• If the inventory task was initiated on November 20, 2022, Manifest-related files of the inventory were placed in the following path in the destination bucket.

cos_bucket_inventory/1250000000/examplebucket/disposable/20221120/manifest.json
cos_bucket_inventory/1250000000/examplebucket/disposable/20221120/manifest.checksum

POST /?inventory&id=disposable 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>disposable</Id>
    <Destination>
        <COSBucketDestination>
            <Format>CSV</Format>
            <AccountId>100000000001</AccountId>
            <Bucket>qcs::cos:city::inventorybucket-1250000000</Bucket>
            <Prefix>cos_bucket_inventory</Prefix>
        </COSBucketDestination>
    </Destination>
    <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 is submitted 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****