tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Cloud Object Storage
    Documentation
    Download PDF

    GET Bucket Inventory

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

      Overview

      This API is used to query an inventory job of a bucket. When calling this API, you need to specify the inventory job ID and carry a request signature. For more information, please see Inventory Overview.
      Note:
      To call this API, ensure that you have the necessary permission on the bucket inventory job.
      The bucket owner has such permission by default. If you do not have the permission, you can request it from the bucket owner.
      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

      GET /?inventory&id=inventory-configuration-ID HTTP/1.1
      Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
      Date: GMT Date
      Authorization: Auth String
      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 GET 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

      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:
      <InventoryConfiguration>
          <Id>list1</Id>
          <IsEnabled>true</IsEnabled>
          <Destination>
              <COSBucketDestination>
                  <Format>CSV</Format>
                  <AccountId>1250000000</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
      InventoryConfiguration
      None
      Inventory configuration
      Container
      Id
      InventoryConfiguration
      Inventory ID, corresponding to the request parameter Id
      Container
      IsEnabled
      InventoryConfiguration
      Whether the inventory is enabled
      true: Yes
      false: No (no inventory will be generated.)
      String
      IncludedObjectVersions
      InventoryConfiguration
      Whether object versions are included in the inventory
      All: Yes (the inventory includes all object versions and the additional fields VersionId, IsLatest, and DeleteMarker.)
      Current: No
      String
      Filter
      InventoryConfiguration
      Filters objects prefixed with the specified value to analyze.
      Container
      And
      Filter
      When you filter the objects to analyze, if both conditions Prefix and Tag are required, use the And container.
      Container
      Prefix
      And
      Prefix of the objects to analyze
      String
      Tag
      And
      When you filter the objects to analyze, you can use one or multiple object tags as a filter condition.
      Container
      Period
      Filter
      Creation time range of the objects to analyze
      Container
      StartTime
      Period
      Creation start time of the objects to analyze. The parameter is a timestamp in seconds, for example, 1568688761.
      String
      EndTime
      Period
      Creation end time of the objects to analyze. The parameter is a timestamp in seconds, for example, 1568688762.
      String
      OptionalFields
      InventoryConfiguration
      Analysis dimensions to include in the inventory result
      Container
      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
      Schedule
      InventoryConfiguration
      Inventory job cycle
      Container
      Frequency
      Schedule
      Frequency of the inventory job, which can be daily or weekly
      String
      Destination
      InventoryConfiguration
      Information about the inventory result destination
      Container
      COSBucketDestination
      Destination
      Information about the bucket that stores the exported inventory result
      Container
      Bucket
      COSBucketDestination
      Bucket name
      String
      AccountId
      COSBucketDestination
      ID of the bucket owner
      String
      Prefix
      COSBucketDestination
      Prefix of the inventory result
      String
      Format
      COSBucketDestination
      Format of the inventory result. Valid values: CSV, ORC
      String
      Encryption
      COSBucketDestination
      Server-side encryption for the inventory result
      Container
      SSE-COS
      Encryption
      Encryption with COS-managed key
      Container

      Error codes

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

      Examples

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

      Request

      The following example queries the list1 inventory job configuration of the examplebucket-1250000000 bucket:
      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.ap-guangzhou.myqcloud.com

      Response

      After the request above is made, COS returns the following response, indicating that the inventory job list1 is currently enabled in the bucket:
      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.
      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: 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: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>
          </OptionalFields>
      </InventoryConfiguration>

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

      Request

      The following example queries the list2 inventory job configuration of the examplebucket-1250000000 bucket:
      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.ap-guangzhou.myqcloud.com

      Response

      After the request above is made, COS returns the following response indicating that the inventory job list2 is currently enabled in the bucket.
      Objects to analyze: objects prefixed with myPrefix and tagged with {age:18} and all their versions in the examplebucket-1250000000 bucket
      Analysis frequency: daily
      Analysis dimensions: Size, LastModifiedDate, StorageClass, ETag, and Tag
      The result will be stored in the inventorybucket-1250000000 bucket as a CSV file.
      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: 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: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>
      
      Contact Us

      Contact our sales team or business advisors to help your business.

      Contact Us
      Technical Support

      Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

      Submit a Ticket
      7x24 Phone Support
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      Privacy PolicyLegalCookie Policy