Tenant Cloud Storage Cloud Object Storage API References Querying the Object List

Querying the Object List

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

Description

The GET Bucket request is equivalent to the List Objects request and can be used to list some or all objects in a bucket. To call this API, you need to have permission to read the bucket.

Request

Request Example 

GET / HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: GMT Date
Authorization: Auth String

Note:

Authorization: Auth String (See Request Signature for details.)

Request Header

Common Headers

This request uses common request headers. For details, see Common Request Headers.

Non-common Headers

This request has no special request header information.

Request Parameters

Name Type Description Required
prefix string Prefix matching, used to specify the file prefix address to be returned. No
delimiter string The delimiter is a character. If there is prefix is specified, the same paths from prefix to delimiter are grouped into one category and defined as Common Prefixe and all Common Prefixes are listed. If no prefix is specified, it starts from the beginning of the path. No
encoding-type string Specifies Encoding type of the returned value. Valid value: url. No
marker string By default, entries are listed in UTF-8 binary order, starting from the marker. No
max-keys string The maximum number (up to 1,000) of keys returned in the response. Defaults to 1000. No

Request Body

The request does not have a request body.

Response

Response Headers

Common Response Headers

This response uses common response headers. For details, see Common Response Headers.

Special Response Headers

There are no special response headers for this response operation.

Response Body

A successful query returns application/xml data that includes the object information in the bucket.

<?xml version='1.0' encoding='utf-8' ?>
<ListBucketResult>
    <Name>examplebucket-1250000000</Name>
    <Encoding-Type>url</Encoding-Type>
    <Prefix>ela</Prefix>
    <Marker/>
    <MaxKeys>1000</MaxKeys>
    <Delimiter>/</Delimiter>
    <IsTruncated>false</IsTruncated>
    <NextMarker>exampleobject.txt</NextMarker>
    <Contents>
        <Key>photo</Key>
        <LastModified>2017-06-23T12:33:26.000Z</LastModified>
        <ETag>\"79f2a852fac7e826c9f4dbe037f8a63b\"</ETag>
        <Size>10485760</Size>
        <Owner>
           <ID>1250000000</ID>
        </Owner>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <CommonPrefixes>
      <Prefix>example</Prefix>
    </CommonPrefixes>
</ListBucketResult>

The data are described as follows:

Node Name (Keyword) Parent Node Description Type
ListBucketResult No Stores the result of the GET Bucket request. Container

Content of ListBucketResult:

Node Name (Keyword) Parent Node Description Type
Name ListBucketResult Bucket information string
Encoding-Type ListBucketResult Encoding Format string
Prefix ListBucketResult Prefix matching is used to specify the prefix address of the file returned by the response request. string
Marker ListBucketResult By default, entries are listed in UTF-8 binary order, starting from the marker. string
MaxKeys ListBucketResult Maximum number of keys returned in a single response request. string
Delimiter ListBucketResult The delimiter is a character. If there is prefix is specified, the same paths from prefix to delimiter are grouped into one category and defined as Common Prefixe and all Common Prefixes are listed. If no prefix is specified, it starts from the beginning of the path. string
IsTruncated ListBucketResult Indicates whether the returned list is truncated. Valid Boolean value: true, false. boolean
NextMarker ListBucketResult If the returned entries are truncated, NextMarker is the starting point of the next entry. string
Contents ListBucketResult Metadata Information Container
CommonPrefixes ListBucketResult The same paths from Prefix to delimiter are grouped into one category and defined as Common Prefix. Container

Content of Contents:

Node Name (Keyword) Parent Node Description Type
Key ListBucketResult.Contents Object Key string
LastModified ListBucketResult.Contents Time the object was last modified. string
ETag ListBucketResult.Contents The MD-5 algorithm checksum of the file. string
Size ListBucketResult.Contents Object size, in bytes string
Owner ListBucketResult.Contents Information of the object owner Container
StorageClass ListBucketResult.Contents Object storage class. Enumerated values: STANDARD, STANDARD_IA, ARCHIVE. string

Content of Owner:

Node Name (Keyword) Parent Node Description Type
ID ListBucketResult.Contents.Owner APPID of the Bucket string

Content of CommonPrefixes:

Node Name (Keyword) Parent Node Description Type
Prefix ListBucketResult.CommonPrefixes A single common prefix string string

Error Code

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

Practical Case

Request 

GET / HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: Wed, 18 Oct 2014 22:32:00 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&q-sign-time=1484213451;32557109451&q-key-time=1484213451;32557109451&q-header-list=host&q-url-param-list=&q-signature=0336a1fc8350c74b6c081d4dff8e7a2db9007dc

Response 

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 1132
Connection: keep-alive
Vary: Accept-Encoding
Date: Wed, 18 Oct 2014 22:32:00 GMT
x-cos-request-id: NTg3NzRjY2VfYmRjMzVfMTc5M182MmIyNg==

<?xml version='1.0' encoding='utf-8' ?>
<ListBucketResult>
    <Name>examplebucket-1250000000</Name>
    <Encoding-Type>url</Encoding-Type>
    <Prefix>ela</Prefix>
    <Marker/>
    <MaxKeys>1000</MaxKeys>
    <Delimiter>/</Delimiter>
    <IsTruncated>false</IsTruncated>
    <NextMarker>exampleobject.txt</NextMarker>
    <Contents>
        <Key>photo</Key>
        <LastModified>2017-06-23T12:33:26.000Z</LastModified>
        <ETag>\"79f2a852fac7e826c9f4dbe037f8a63b\"</ETag>
        <Size>10485760</Size>
        <Owner>
            <ID>1250000001</ID>
        </Owner>
    <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>picture</Key>
        <LastModified>2017-06-23T12:33:26.000Z</LastModified>
        <ETag>\"3f9a5dbff88b25b769fa6304902b5d9d\"</ETag>
        <Size>10485760</Size>
        <Owner>
            <ID>1250000002</ID>
        </Owner>
    <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>file</Key>
        <LastModified>2017-06-23T12:33:26.000Z</LastModified>
        <ETag>\"39bfb88c11c65ed6424d2e1cd4db1826\"</ETag>
        <Size>10485760</Size>
        <Owner>
            <ID>1250000003</ID>
        </Owner>
    <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>world</Key>
        <LastModified>2017-06-23T12:33:26.000Z</LastModified>
        <ETag>\"fb31459ad10289ff49327fd91a3e1f6a\"</ETag>
        <Size>4</Size>
        <Owner>
            <ID>1250000004</ID>
        </Owner>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
</ListBucketResult>