List Bucket Inventory Configurations

Last updated: 2021-11-17 12:15:14

    Overview

    This API is used to query all inventory jobs set for a bucket. You can configure up to 1,000 inventory jobs for a bucket.

    This request supports returning the results in multiple responses. Each response can contain up to 100 inventory jobs. Please pay attention to the value of IsTruncated in the request.

    • If the value of IsTruncated is false, all inventory jobs of the bucket have been listed.
    • If the value of IsTruncated is true and NextContinuationToken carries a value, you can pass this value to continuation-token in the next request to obtain the remaining inventory jobs from the next response.

    For more information, please see Inventory Overview.

    Note:

    To call this API, make sure that you have the necessary permission for bucket inventory jobs; the bucket owner has this permission by default. If you do not have it, you should request it from the bucket owner first.

    API Explorer is recommended.
    Debug
    API Explorer makes it easy to make online API calls, verify signatures, generate SDK code, search for APIs, etc. You can also use it to query the content of each request as well as its response.

    Request

    Sample request

    GET /?inventory HTTP/1.1
    Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
    Date: GMT Date
    Authorization: Auth String
    
    Note:

    Request parameters

    The request parameter is as follows:

    Parameter Description Type Required
    continuation-token If the value of IsTruncated is true in the last COS response and NextContinuationToken carries a value, you can pass this value to continuation-token to obtain the inventory jobs in the response.
    Default value: None
    String No

    Request headers

    This API only uses Common Request Headers.

    Request body

    The request body of this request is empty.

    Response

    Response headers

    This API only returns Common Response Headers.

    Response body

    The response body returns application/xml data. The following contains all the nodes:

    <ListInventoryConfigurationResult>
    <InventoryConfiguration>
        <Id>list1</Id>
        <IsEnabled>True</IsEnabled>
        <Destination>
            <COSBucketDestination>
                <Format>CSV</Format>
                <AccountId>1250000000</AccountId>
                <Bucket>qcs::cos:ap-beijing::examplebucket-1250000000</Bucket>
                <Prefix>list1</Prefix>
                <SSE-COS></SSE-COS>
            </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>IsMultipartUpload</Field>
            <Field>ReplicationStatus</Field>
        </OptionalFields>
    </InventoryConfiguration>
    <InventoryConfiguration>
        <Id>list2</Id>
        <IsEnabled>True</IsEnabled>
        <Destination>
            <COSBucketDestination>
                <Format>CSV</Format>
                <AccountId>1250000000</AccountId>
                <Bucket>qcs::cos:ap-beijing::examplebucket-1250000000</Bucket>
                <Prefix>list2</Prefix>
                <SSE-COS></SSE-COS>
            </COSBucketDestination>
        </Destination>
        <Schedule>
            <Frequency>Weekly</Frequency>
        </Schedule>
        <Filter>
            <Prefix>myPrefix2</Prefix>
        </Filter>
        <IncludedObjectVersions>All</IncludedObjectVersions>
        <OptionalFields>
            <Field>Size</Field>
            <Field>LastModifiedDate</Field>
            <Field>ETag</Field>
            <Field>StorageClass</Field>
        </OptionalFields>
    </InventoryConfiguration>
    <IsTruncated>false</IsTruncated>
    ------If ContinuationToken was provided in the request---
    <ContinuationToken>...</ContinuationToken>
    <IsTruncated>true</IsTruncated>
    <NextContinuationToken>1ueSDFASDF1Tr/XDAFdadEADadf2J/wm36Hy4vbOwM=</NextContinuationToken>
    </ListInventoryConfigurationResult>
    

    The nodes are described as follows:

    Node Name Parent Node Description Type
    ListInventoryConfigurationResult None Information about all inventory jobs of the bucket Container
    InventoryConfiguration ListInventoryConfigurationResult Detailed configuration of an inventory job. For the XML structure, please see GET Bucket inventory. Container
    IsTruncated ListInventoryConfigurationResult Whether all inventory jobs have been listed. If yes, the value is false. Otherwise, the value is true. Boolean
    ContinuationToken ListInventoryConfigurationResult Identifier of the current response. This parameter corresponds to the continuation-token request parameter. String
    NextContinuationToken ListInventoryConfigurationResult Identifier of the next response. You can pass the value of this parameter to continuation-token and initiate a GET request to obtain the inventory jobs from the next response. String

    Error codes

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

    Example

    Request

    The following example queries the inventory jobs of the examplebucket-1250000000 bucket:

    GET /?inventory HTTP/1.1
    Date: Mon, 28 Aug 2018 02:53:38 GMT
    Authorization: q-sign-algorithm=sha1&q-ak=AKIDZfbOAo7cllgPvF9cXFrJD0a1ICvR98JM&q-sign-time=1503895278;1503895638&q-key-time=1503895278;1503895638&q-header-list=host&q-url-param-list=inventory&q-signature=f77900be432072b16afd8222b4b349aabd837cb9
    Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
    

    Response

    After the request above is made, COS returns the following response, indicating that the inventory jobs list1 and list2 are set for the bucket.

    Inventory job list1

    • Objects to analyze: objects prefixed with myPrefix and all their versions in the examplebucket-1250000000 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.

    Inventory job list2

    • Objects to analyze: objects prefixed with myPrefix2 and all their versions in the examplebucket-1250000000 bucket
    • Analysis frequency: once a week
      Analysis dimensions: Size, LastModifiedDate, StorageClass, and ETag
    • Analysis result: to be stored in the examplebucket-1250000000 bucket as a CSV file, which is prefixed with list2 and encrypted with SSE-COS.

    Assume that 100 inventory jobs are listed in this response. If the value of IsTruncated is true, COS will return NextContinuationToken, whose value can be passed to continuation-token for a GET request to obtain the inventory jobs from the next response.

    HTTP/1.1 200 OK
    Content-Type: application/xml
    Content-Length: 331
    Date: Mon, 28 Aug 2018 02:53:39 GMT
    Server: tencent-cos
    x-cos-request-id: NTlhMzg1ZWVfMjQ4OGY3MGFfMWE1NF8****
    <?xml version = "1.0" encoding = "UTF-8">
    <ListInventoryConfigurationResult xmlns = "http://....">
    <InventoryConfiguration>
        <Id>list1</Id>
        <IsEnabled>True</IsEnabled>
        <Destination>
            <COSBucketDestination>
                <Format>CSV</Format>
                <AccountId>1250000000</AccountId>
                <Bucket>qcs::cos:ap-beijing::examplebucket-1250000000</Bucket>
                <Prefix>list1</Prefix>
                <SSE-COS></SSE-COS>
            </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>IsMultipartUpload</Field>
            <Field>ReplicationStatus</Field>
        </OptionalFields>
    </InventoryConfiguration>
    <InventoryConfiguration>
        <Id>list2</Id>
        <IsEnabled>True</IsEnabled>
        <Destination>
            <COSBucketDestination>
                <Format>CSV</Format>
                <AccountId>1250000000</AccountId>
                <Bucket>qcs::cos:ap-beijing::examplebucket-1250000000</Bucket>
                <Prefix>list2</Prefix>
                <SSE-COS></SSE-COS>
            </COSBucketDestination>
        </Destination>
        <Schedule>
            <Frequency>Weekly</Frequency>
        </Schedule>
        <Filter>
            <Prefix>myPrefix2</Prefix>
        </Filter>
        <IncludedObjectVersions>All</IncludedObjectVersions>
        <OptionalFields>
            <Field>Size</Field>
            <Field>LastModifiedDate</Field>
            <Field>ETag</Field>
            <Field>StorageClass</Field>
        </OptionalFields>
    </InventoryConfiguration>
    <IsTruncated>false</IsTruncated>
    ------If ContinuationToken was provided in the request---
    <ContinuationToken>...</ContinuationToken>
    <IsTruncated>true</IsTruncated>
    <NextContinuationToken>1ueSDFASDF1Tr/XDAFdadEADadf2J/wm36Hy4vbOwM=</NextContinuationToken>
    </ListInventoryConfigurationResult>