文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>对象存储>向量存储与检索>向量存储桶>SDK 文档>Go SDK>向量桶操作>列出向量桶

列出向量桶

最近更新时间：2026-04-01 15:41:32

我的收藏

本页目录：

简介

本文档提供关于对象存储（COS）向量存储桶服务中列出向量桶（ListVectorBuckets）API 的 Go SDK 使用说明和示例代码。

功能说明

ListVectorBuckets 接口用于获取当前账号在对应地域下的所有向量存储桶列表。该接口支持分页拉取，并支持通过前缀对返回的桶名称进行过滤。

方法原型

func (s *VectorService) ListVectorBuckets(ctx context.Context, opt *ListVectorBucketsOptions) (*ListVectorBucketsResult, *Response, error)

请求参数说明

ListVectorBucketsOptions 结构体字段说明：
参数
描述
类型
是否必填
MaxResults
单次返回的最大结果数。最小值1，最大值500。默认值100。
int
否
NextToken
分页令牌，用于获取下一页数据。
string
否
Prefix
桶名称前缀过滤，将响应限制为以指定向量桶名称前缀开头的向量桶。
string
否

返回结果说明

调用成功后，将返回 (*ListVectorBucketsResult, *Response, error) 三个值。
ListVectorBucketsResult 结构体字段说明：
参数
描述
类型
NextToken
下一页的分页标记。如果响应结果已被截断，此字段会有值；如果结果已全部返回，此字段为空。
string
VectorBuckets
包含本页检索到的所有向量桶简要信息的列表。
[]VectorBucketBrief
VectorBucketBrief 结构体字段说明：
参数
描述
类型
CreationTime
向量桶的创建时间戳（毫秒级）。
int64
VectorBucketQcs
向量桶的唯一资源标识符 (QCS)。
string
VectorBucketName
向量桶的名称。
string
其他返回值说明：
返回值
描述
类型
resp
响应头信息，包含 HTTP 响应的详细对象等。
*cos.Response
err
错误信息。如果请求成功，返回 nil。
error
如果请求失败，将返回非 nil 的 error。向量检索相关的业务错误会封装为 *cos.VectorErrorResponse 结构，您可以通过 cos.IsVectorError() 辅助函数判断并获取详细错误信息。详细的错误处理方式、VectorErrorResponse 结构体说明及服务端错误码列表请参见 异常处理 文档。

使用案例

package main

import (
    "context"
    "fmt"
    "net/http"
    "os"

    cos "github.com/tencentyun/cos-go-sdk-v5"
)

func main() {
    // 生成 Vector 基础 URL
    vectorURL, _ := cos.NewVectorURL("ap-guangzhou", true)
    
    // 从环境变量中获取临时访问凭证
    secretID := os.Getenv("COS_VECTORS_TMP_SECRET_ID")
    secretKey := os.Getenv("COS_VECTORS_TMP_SECRET_KEY")
    sessionToken := os.Getenv("COS_VECTORS_SESSION_TOKEN")

    // 初始化 Client
    client := cos.NewClient(&cos.BaseURL{VectorURL: vectorURL}, &http.Client{
        Transport: &cos.AuthorizationTransport{
            SecretID:     secretID,
            SecretKey:    secretKey,
            SessionToken: sessionToken,
        },
    })

    // 查询参数
    opt := &cos.ListVectorBucketsOptions{
        MaxResults: 100,      // 最大返回数量，默认 100，最大 500
        // Prefix:  "example", // 可通过前缀过滤
    }

    res, _, err := client.Vector.ListVectorBuckets(context.Background(), opt)
    if err != nil {
        if vecErr, ok := cos.IsVectorError(err); ok {
            fmt.Printf("向量服务错误，错误码: %s, 错误信息: %s, 请求ID: %s\\n",
                vecErr.Code, vecErr.Message, vecErr.RequestID)
        } else {
            fmt.Printf("请求失败: %v\\n", err)
        }
        return
    }

    fmt.Println("当前拥有的向量桶列表：")
    for _, bucket := range res.VectorBuckets {
        fmt.Printf("桶名称: %s, 创建时间: %d\\n", bucket.VectorBucketName, bucket.CreationTime)
    }

    // 如果有分页，可以通过 res.NextToken 继续拉取下一页
    if res.NextToken != "" {
        fmt.Printf("还有更多数据，拉取下一页需传入 Token: %s\\n", res.NextToken)
    }
}
中国站