tencent cloud

All product documents
APIs
DocumentationAPIsCloud Object StorageService APIsGET Service（List Buckets）
GET Service（List Buckets）
Last updated: 2024-03-28 15:36:00
GET Service（List Buckets）
Last updated: 2024-03-28 15:36:00

Overview

This API is used to query the list of all buckets under a requester's account or in a specific region.


Request

Sample request

Sample 1
GET / HTTP/1.1
Host: service.cos.myqcloud.com
Date: GMT Date
Authorization: Auth String
Sample 2
GET / HTTP/1.1
Host: cos.<Region>.myqcloud.com
Date: GMT Date
Authorization: Auth String
Note:
Authorization: Auth String (See Request Signature for details.)
Host: To query the list of all buckets, set it to service.cos.myqcloud.com. To query the list of buckets in a specified region, set it to cos.&lt;Region>.myqcloud.com, where <Region> is a COS available region (see Regions and Access Endpoints).

Request parameters

GetService supports filtering buckets by bucket tag, region, and creation time through request parameters. To filter buckets by tag, only one tag can be passed in. If a bucket has multiple tags, as long as any of them is hit, the bucket will be returned.
Field
Description
Type
Required
tagkey
Filters buckets by bucket tag. Only one tag can be passed in. tagkey is used to pass in the tag key.
string
No
tagvalue
Filters buckets by bucket tag. Only one tag can be passed in. tagvalue is used to pass in the tag value.
string
No
region
Filters buckets by region, such as region=ap-beijing. For the regions supported by COS, see Regions and Access Endpoints.
string
No
create-time
GMT timestamp, which is used together with the range parameter to filter buckets by creation time, such as create-time=1642662645.
Timestamp
No
range
Filters buckets by creation time together with the create-time parameter. Enumerated values: lt (creation time before create-time), gt (creation time after create-time), lte (creation time before or at create-time), gte (creation time after or at create-time).
string
No
When the bucket tag authorization is different from the GetService authorization, the authentication and response of the GetService request are as follows:
Bucket tag Authorization Status
`GetService` Authorization Status
`GetService` Request
Response
The root account passes the bucket tag authorization and grants the sub-account the resource operation permission of the bucket tag `tagA`.
`GetService` permission not granted.
With bucket tag parameter `tagA`
List of buckets containing bucket tag `tagA`
Without bucket tag parameter
Access Denied
`GetService` permission granted
With bucket tag parameter `tagA`
List of buckets containing bucket tag `tagA`
Without bucket tag parameter
List of all buckets
The root account doesn't pass the bucket tag authorization or grant the sub-account the resource operation permission of the bucket tag `tagA`.
`GetService` permission not granted.
With bucket tag parameter `tagA`
Access Denied
Without bucket tag parameter
Access Denied
`GetService` permission granted
With bucket tag parameter `tagA`
List of buckets containing bucket tag `tagA`
Without bucket tag parameter
List of all buckets


Request headers

This API only uses Common Request Headers.

Request body

This API does not have a request body.

Response

Response headers

This API only returns Common Response Headers.

Response body

A successful query returns application/xml data that includes the list of all buckets or the list of buckets in a specific region.
<ListAllMyBucketsResult>
    <Owner>
        <ID>string</ID>
        <DisplayName>string</DisplayName>
    </Owner>
    <Buckets>
        <Bucket>
            <Name>string</Name>
            <Location>Enum</Location>
            <CreationDate>date</CreationDate>
        </Bucket>
        <Bucket>
            <Name>string</Name>
            <Location>Enum</Location>
            <CreationDate>date</CreationDate>
        </Bucket>
    </Buckets>
</ListAllMyBucketsResult>
The nodes are described as follows:
Node Name (Keyword)
Parent Node
Description
Type
ListAllMyBucketsResult
None
Stores the result of the GET Service request
Container
Content of ListAllMyBucketsResult:
Node Name (Keyword)
Parent Node
Description
Type
Owner
ListAllMyBucketsResult
Bucket owner information
Container
Buckets
ListAllMyBucketsResult
Bucket list
Container
Content of Owner:
Node Name (Keyword)
Parent Node
Description
Type
ID
ListAllMyBucketsResult.Owner
Complete ID of the bucket owner in the format of qcs::cam::uin/[OwnerUin]:uin/[OwnerUin]
Example: qcs::cam::uin/100000000001:uin/100000000001
string
DisplayName
ListAllMyBucketsResult.Owner
Bucket owner name
string
Content of Buckets:
Node Name (Keyword)
Parent Node
Description
Type
Bucket
ListAllMyBucketsResult.Buckets
Bucket information
Container
Content of Buckets.Bucket:
Node Name (Keyword)
Parent Node
Description
Type
Name
ListAllMyBucketsResult.Buckets.Bucket
Bucket name in the format of <BucketName-APPID>
Example: examplebucket-1250000000
string
Location
ListAllMyBucketsResult.Buckets.Bucket
Region of the bucket. For the enumerated values, please see Regions and Access Endpoints.
Example: ap-beijing, ap-hongkong, eu-frankfurt
Enum
CreationDate
ListAllMyBucketsResult.Buckets.Bucket
Bucket creation time in ISO 8601 format. Example: 2019-05-24T10:56:40Z
date

Error codes

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

Examples

Example 1. Querying the list of all buckets

Request

GET / HTTP/1.1
Host: service.cos.myqcloud.com
Date: Fri, 24 May 2019 11:59:50 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1558699190;1558706390&q-key-time=1558699190;1558706390&q-header-list=date;host&q-url-param-list=&q-signature=89fa1f6a56c34e460f3db4d65f928eaf034a****
Connection: close

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 805
Connection: close
Date: Fri, 24 May 2019 11:59:51 GMT
Server: tencent-cos
x-cos-request-id: NWNlN2RjYjdfOGFiMjM1MGFfNTVjMl8zMmI1****

<ListAllMyBucketsResult>
    <Owner>
        <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
        <DisplayName>100000000001</DisplayName>
    </Owner>
    <Buckets>
        <Bucket>
            <Name>examplebucket1-1250000000</Name>
            <Location>ap-beijing</Location>
            <CreationDate>2019-05-24T11:49:50Z</CreationDate>
        </Bucket>
        <Bucket>
            <Name>examplebucket2-1250000000</Name>
            <Location>ap-beijing</Location>
            <CreationDate>2019-05-24T11:51:50Z</CreationDate>
        </Bucket>
        <Bucket>
            <Name>examplebucket3-1250000000</Name>
            <Location>eu-frankfurt</Location>
            <CreationDate>2019-05-24T11:53:50Z</CreationDate>
        </Bucket>
        <Bucket>
            <Name>examplebucket4-1250000000</Name>
            <Location>eu-frankfurt</Location>
            <CreationDate>2019-05-24T11:55:50Z</CreationDate>
        </Bucket>
    </Buckets>
</ListAllMyBucketsResult>

Example 2. Querying the list of buckets in a specific region (filtered by domain name)

Request

GET / HTTP/1.1
Host: cos.ap-beijing.myqcloud.com
Date: Fri, 24 May 2019 11:59:51 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1558699191;1558706391&q-key-time=1558699191;1558706391&q-header-list=date;host&q-url-param-list=&q-signature=c3f55f4ce2800fb343cf85ff536a9185a0c1****
Connection: close

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 495
Connection: close
Date: Fri, 24 May 2019 11:59:51 GMT
Server: tencent-cos
x-cos-request-id: NWNlN2RjYjdfZjhjODBiMDlfOWNlNF9hYzc2****

<ListAllMyBucketsResult>
    <Owner>
        <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
        <DisplayName>100000000001</DisplayName>
    </Owner>
    <Buckets>
        <Bucket>
            <Name>examplebucket1-1250000000</Name>
            <Location>ap-beijing</Location>
            <CreationDate>2019-05-24T11:49:50Z</CreationDate>
        </Bucket>
        <Bucket>
            <Name>examplebucket2-1250000000</Name>
            <Location>ap-beijing</Location>
            <CreationDate>2019-05-24T11:51:50Z</CreationDate>
        </Bucket>
    </Buckets>
</ListAllMyBucketsResult>

Example 3. Querying the list of buckets in a specific region (filtered by request parameter)

Request

GET /?region=ap-beijing HTTP/1.1
Host: service.cos.myqcloud.com
Date: Fri, 24 May 2019 11:59:51 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1558699191;1558706391&q-key-time=1558699191;1558706391&q-header-list=date;host&q-url-param-list=&q-signature=c3f55f4ce2800fb343cf85ff536a9185a0c1****
Connection: close

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 495
Connection: close
Date: Fri, 24 May 2019 11:59:51 GMT
Server: tencent-cos
x-cos-request-id: NWNlN2RjYjdfZjhjODBiMDlfOWNlNF9hYzc2****

<ListAllMyBucketsResult>
    <Owner>
        <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
        <DisplayName>100000000001</DisplayName>
    </Owner>
    <Buckets>
        <Bucket>
            <Name>examplebucket1-</Name>
            <Location>ap-beijing</Location>
            <CreationDate>2019-05-24T11:49:50Z</CreationDate>
        </Bucket>
        <Bucket>
            <Name>examplebucket2-1250000000</Name>
            <Location>ap-beijing</Location>
            <CreationDate>2019-05-24T11:51:50Z</CreationDate>
        </Bucket>
    </Buckets>
</ListAllMyBucketsResult>

Example 4. Filtering buckets by the specified tag

The tag of bucket examplebucket-1250000000 is 
<key1, value1>
and the tags of bucket examplebucket1-1250000000 are 
<key1, value1> and <key2, value2>

Request

GET /?tagkey=key1&tagvalue=value1 HTTP/1.1
Host: service.cos.myqcloud.com
Date: Fri, 24 May 2019 11:59:51 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1558699191;1558706391&q-key-time=1558699191;1558706391&q-header-list=date;host&q-url-param-list=&q-signature=c3f55f4ce2800fb343cf85ff536a9185a0c1****
Connection: close

Response

HTTP/1.1 200 OK
Content-Length: 378
Content-Type: application/xml
Server: tencent-cos
Connection: keep-alive
Date: Thu, 20 Oct 2022 07:29:40 GMT
x-cos-request-id: NjM1MGY4ZTRfMWViMjM1MGFfYjg3MV8xNjdk****

<ListAllMyBucketsResult>
    <Owner>
        <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
        <DisplayName>100000000001</DisplayName>
    </Owner>
    <Buckets>
        <Bucket>
            <Name>examplebucket-1250000000 </Name>
            <Location>ap-guangzhou</Location>
            <CreationDate>2022-04-11T03:01:49Z</CreationDate>
            <BucketType>cos</BucketType>
        </Bucket>
    </Buckets>
    <Buckets>
        <Bucket>
            <Name>examplebucket1-1250000000 </Name>
            <Location>ap-guangzhou</Location>
            <CreationDate>2022-04-12T03:01:49Z</CreationDate>
            <BucketType>cos</BucketType>
        </Bucket>
    </Buckets>
</ListAllMyBucketsResult>

Example 5. Filtering buckets by creation time

List buckets created before 2022-1-20 15:10:45.

Request

GET /?range=lt&create-time=1642662645 HTTP/1.1
Host: service.cos.myqcloud.com
User-Agent: curl/7.64.1
Accept: */*
Authorization: q-sign-algorithm=sha1&q-ak=AKIDYv3vWrwkHXVDfqk*****&q-sign-time=1667448802;1668448852&q-key-time=1667448802;1668448852&q-url-param-list=create-time;range&q-header-list=host&q-signature=a043c0593c8c4cd1caf570******

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 5566
Connection: keep-alive
Date: Thu, 03 Nov 2022 04:14:23 GMT
Server: tencent-cos
x-cos-request-id: NjM2MzQwMWZfMmJiMjM1MGFfYTc******

<ListAllMyBucketsResult>
    <Owner>
        <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
        <DisplayName>100000000001</DisplayName>
    </Owner>
    <Buckets>
        <Bucket>
            <Name>examplebucket-1250000000</Name>
            <Location>ap-beijing</Location>
            <CreationDate>2021-11-23T03:02:12Z</CreationDate>
            <BucketType>cos</BucketType>
        </Bucket>
    </Buckets>
</ListAllMyBucketsResult>

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback

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