tencent cloud

Querying a Bucket List
Last updated: 2025-08-15 16:30:18
Querying a Bucket List
Last updated: 2025-08-15 16:30:18

Overview

This document provides an API overview and SDK example code for querying the bucket list.

Notes

Before using bucket-related operations, you must have relevant permissions. Specifically:
To query the bucket list, when you perform authorization policy, set the action to cos:GetService. For more authorization, see CAM-Enabled API.

Related Examples

Feature Name
Description
Sample code
Querying the Bucket List
Query the list of all buckets under a specified account.

Querying the Bucket List

Feature Overview

Query the list of all buckets under a specified account.

Method Prototype

func (s *ServiceService) Get(ctx context.Context, opt ...*ServiceGetOptions) (*ServiceGetResult, *Response, error)

Request Example

package main

import (
"context"
"fmt"
"github.com/tencentyun/cos-go-sdk-v5"
"net/http"
"net/url"
"os"
)

func main() {
// Bucket name, composed of bucketname-appid. The appid must be entered. You can view the bucket name in the COS console. https://console.tencentcloud.com/cos5/bucket
// Replace with the user's region. The bucket region can be viewed in the "bucket overview" section of the COS console https://console.tencentcloud.com/. For details about regions, see https://www.tencentcloud.com/document/product/436/6224?from_cn_redirect=1.
u, _ := url.Parse("https://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com")
su, _ := url.Parse("https://service.cos.myqcloud.com")
// If only calling the GetService API, you only need to configure ServiceURL. The SDK internally sets ServiceURL to https://service.cos.myqcloud.com by default.
b := &cos.BaseURL{BucketURL: u, ServiceURL: su}
client := cos.NewClient(b, &http.Client{
Transport: &cos.AuthorizationTransport{
// Get key through environment variables
// The environment variable SECRETID means the user's SecretId. View the key in the Cloud Access Management console at https://console.tencentcloud.com/cam/capi.
SecretID: os.Getenv("SECRETID"), // User's SecretId. It is recommended to use sub-account keys and follow the principle of least privilege to reduce usage risks. For obtaining sub-account keys, see https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1.
// The environment variable SECRETKEY means the user's SecretKey. View the key in the CAM console at https://console.tencentcloud.com/cam/capi.
SecretKey: os.Getenv("SECRETKEY"), // User's SecretKey. It is recommended to use sub-account keys and follow the principle of least privilege to reduce usage risks. For obtaining sub-account keys, see https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1.
},
})
res, _, err := client.Service.Get(context.Background())
if err != nil {
panic(err)
}
for _, bucket := range res.Buckets {
fmt.Printf("%+v\\n", bucket)
}
}

Parameter Description

type ServiceGetOptions struct {
TagKey string
TagValue string
MaxKeys int64
Marker string
Range string
CreateTime int64
Region string
}
Parameter Name
Parameter Description
Type
Required or Not
TagKey
Filter buckets based on bucket tags (composed of tag key and tag value). Only one bucket tag is supported. Use tagkey to input the tag key. If querying buckets by bucket tag, both tagkey and tagvalue are required.
string
No
TagValue
Filter buckets by bucket tags (consisting of tag key and tag value). Only one bucket tag is supported. Use tagvalue to input the tag value. If querying buckets by bucket tag, both tagkey and tagvalue are required.
string
No
MaxKeys
The maximum number of entries returned at a time is 2000 by default, with a maximum of 2000. If the single response does not list all buckets, COS returns a NextMarker node, whose value serves as the marker parameter for the next GetService request.
int
No
Marker
Starting marker, starting from which (excluding), bucket entries are returned in UTF-8 lexicographical order.
string
No
Range
Used with the create-time parameter, it supports time filtering for buckets based on creation time. Supported enumeration values: lt (creation time earlier than create-time), gt (creation time later than create-time), lte (creation time earlier than or equal to create-time), gte (creation time later than or equal to create-time).
string
No
CreateTime
GMT timestamp, used with the range parameter, supports filtering buckets based on creation time, for example create-time=1642662645
int
No
Region
Filter buckets based on region, for example region=ap-beijing
string
No

Return Result Description

The request result is returned through GetServiceResult.
type ServiceGetResult struct {
Owner *Owner
Buckets []Bucket
}
type Owner struct {
ID string
DisplayName string
}
type Bucket struct {
Name string
Region string
CreationDate string
}
Parameter Name
Parameter Description
Type
ID
ID of the bucket owner.
string
DisplayName
Name of the bucket owner.
string
Name
Bucket
string
Region
Region of the Bucket
string
CreationDate
Bucket creation time in ISO 8601 format. Example: 2019-05-24T10:56:40Z.
string

API Operations

For the API interface description of querying the bucket list, please refer to the GET Service (List Buckets) document.
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback