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>
﻿

tencent cloud

Recent Pages

GET Service（List Buckets）

Overview

Request

Sample request

Request parameters

Request headers

Request body

Response

Response headers

Response body

Error codes

Examples

Example 1. Querying the list of all buckets

Request

Response

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

Request

Response

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

Request

Response

Example 4. Filtering buckets by the specified tag

Request

Response

Example 5. Filtering buckets by creation time

Request

Response

Was this page helpful?

Was this page helpful?

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

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`
	`GetService` permission not granted.			Without bucket tag parameter	Access Denied
		`GetService` permission granted	With bucket tag parameter `tagA`	List of buckets containing bucket tag `tagA`
		`GetService` permission granted		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
	`GetService` permission not granted.			Without bucket tag parameter	Access Denied
		`GetService` permission granted	With bucket tag parameter `tagA`	List of buckets containing bucket tag `tagA`
		`GetService` permission granted		Without bucket tag parameter	List of all buckets

Node Name (Keyword)	Parent Node	Description	Type
ListAllMyBucketsResult	None	Stores the result of the `GET Service` request	Container

tencent cloud

Sign Up

Log in

Recent Pages

GET Service（List Buckets）

Overview

Request

Sample request

Request parameters

Request headers

Request body

Response

Response headers

Response body

Error codes

Examples

Example 1. Querying the list of all buckets

Request

Response

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

Request

Response

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

Request

Response

Example 4. Filtering buckets by the specified tag

Request

Response

Example 5. Filtering buckets by creation time

Request

Response

Was this page helpful?

Was this page helpful?