tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Documentation

PUT Bucket Inventory

Last updated: 2024-03-28 18:08:33

    Overview

    This API is used to create an inventory job for a bucket. For more information, see Inventory Overview.
    Note:
    You can create up to 1,000 inventory jobs for each COS bucket.
    You must add a bucket policy to the destination bucket for COS to write the output file of the inventory job to the destination bucket.
    To call this API, ensure that you have obtained required permissions from the bucket owner to operate on the inventory jobs for the bucket. The bucket owner has such permissions by default. For the authorization directions, please see Inventory Overview - Directions.
    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.
    

    Request

    Sample request

    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:
    In Host: <BucketName-APPID>.cos.<Region>.myqcloud.com, <BucketName-APPID> is the bucket name followed by the APPID, such as examplebucket-1250000000 (see Bucket Overview > Basic Information and Bucket Overview > Bucket Naming Conventions), and <Region> is a COS region (see Regions and Access Endpoints).
    Authorization: Auth String (See Request Signature for details.)

    Request parameters

    To call PUT Bucket inventory, specify the following parameter:
    Parameter
    Description
    Type
    Required
    Id
    ID of the inventory job. Default value: None Letters, digits, hyphens (-), underscores (_), and dots (.) are supported.
    String
    Yes

    Request headers

    This API only uses Common Request Headers.

    Request body

    You can configure the inventory job in the request body using the XML markup language. The configuration includes objects to analyze, analysis frequency, analysis dimensions, and the format and destination path of the analysis result. 
    <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</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:
    Node
    Parent Node
    Description
    Type
    Required
    InventoryConfiguration
    None
    Inventory configurations
    Container
    Yes
    Id
    InventoryConfiguration
    Inventory ID, corresponding to the request parameter id
    Container
    Yes
    IsEnabled
    InventoryConfiguration
    Whether to enable the inventory
    true: Yes
    false: No (no inventory will be generated.)
    String
    Yes
    IncludedObjectVersions
    InventoryConfiguration
    Whether to include object versions in the inventory
    All: Yes (the inventory will include all object versions and the additional fields VersionId, IsLatest, and DeleteMarker.)
    Current: No
    String
    Yes
    Filter
    InventoryConfiguration
    Filters objects prefixed with the specified value to analyze.
    Container
    No
    And
    Filter
    When you filter the objects to analyze, if both conditions Prefix and Tag are required, use the And container.
    Container
    No
    Prefix
    And
    Prefix of the objects to analyze
    String
    No
    Tag
    And
    When you filter the objects to analyze, you can use one or multiple object tags as a filter condition.
    Container
    No
    Period
    Filter
    Creation time range of the objects to analyze
    Container
    No
    StartTime
    Period
    Creation start time of the objects to analyze. The parameter is a timestamp in seconds, for example, 1568688761.
    String
    No
    EndTime
    Period
    Creation end time of the objects to analyze. The parameter is a timestamp in seconds, for example, 1568688762.
    String
    No
    OptionalFields
    InventoryConfiguration
    Analysis items to include in the inventory result
    Container
    No
    Field
    OptionalFields
    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.
    String
    No
    Schedule
    InventoryConfiguration
    Inventory job cycle
    Container
    Yes
    Frequency
    Schedule
    Frequency of the inventory job. Enumerated values: Daily, Weekly
    String
    Yes
    Destination
    InventoryConfiguration
    Information about the inventory result destination
    Container
    Yes
    COSBucketDestination
    Destination
    Information about the bucket that stores the exported inventory result
    Container
    Yes
    Bucket
    COSBucketDestination
    Bucket name
    String
    Yes
    AccountId
    COSBucketDestination
    ID of the bucket owner, for example, 100000000001
    String
    No
    Prefix
    COSBucketDestination
    Prefix of the inventory result
    String
    No
    Format
    COSBucketDestination
    Format of the inventory result. Valid value: CSV
    String
    Yes
    Encryption
    COSBucketDestination
    Server-side encryption for the inventory result
    Container
    No
    SSE-COS
    Encryption
    Encryption with COS-managed key. This field can be left empty.
    Container
    No

    Response

    Response headers

    This API only returns Common Response Headers.

    Response body

    The response body is empty.

    Error codes

    This API returns common error responses and error codes. For more information, see Error Codes.

    Examples

    Example 1: Adding an inventory job with a specified object prefix

    Request

    This example adds an inventory job named list1 to the examplebucket-1250000000 bucket.
    Objects to analyze: objects prefixed with myPrefix and all their versions in the 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.
    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.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

    The response below indicates that the inventory job list1 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****

    Example 2: Adding an inventory job with a specified object prefix and object tag

    Request

    This example adds an inventory job named list2 to the examplebucket-1250000000 bucket.
    The object (including its all versions) prefixed with myPrefix and tagged with {age:18} in the bucket will be analyzed.
    Analysis frequency: daily
    Analysis dimensions: Size, LastModifiedDate, StorageClass, ETag, Tag
    The result will be stored in the inventorybucket-1250000000 bucket as a CSV file.
    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.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 request above is made, COS returns the following response, indicating that the inventory task list2 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****

    Example 3: Adding an inventory job that supports outputting of custom headers of the object

    Request

    This example adds an inventory job named list3 to the examplebucket-1250000000 bucket.
    The object (including its all versions) prefixed with myPrefix and tagged with {age:18} in the bucket will be analyzed.
    Analysis frequency: daily
    Analysis dimensions: Size, LastModifiedDate, StorageClass, ETag, Tag, x-cos-meta-myheader
    The result will be stored in the inventorybucket-1250000000 bucket as a CSV file.
    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.ap-guangzhou.myqcloud.com
    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: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 request above is made, COS returns the following response, indicating that the inventory job 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****
    
    Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
    Privacy PolicyLegalCookie Policy