金山云-文档中心-List Indexes

对象存储(KS3)

查看更多结果

未找到含当前关键字的文档标题

页面目录

全部展开全部收起

产品更新动态

未找到含该关键词的产品

文档中心

对象存储(KS3)

API文档

向量存储桶（KS3 Vectors）

索引相关

List Indexes

最近更新时间：2026-11-03 19:52:57



描述

列举向量 Bucket 中的所有向量索引。使用此接口，您必须是这个 Bucket 的拥有者或拥有 ks3:ListIndexes 权限。

单次 List 最大返回索引个数 100，支持分页获取下一批索引列表。List并发度上限为 16 个。

请求

请求语法

POST /ListIndexes HTTP/1.1
Host: ks3vectors-cn-beijing.ksyuncs.com
Authorization: authorization string
Date: Mon, 10 Dec 2025 12:49:14 GMT
Content-Type: application/json

{
  "vectorBucketName": "string",
  "prefix": "string",
  "maxResults": integer
}

使用向量桶 KRN 时，请求体为：

{
  "vectorBucketKrn": "string",
  "prefix": "string",
  "maxResults": integer
}

可通过向量桶名称或向量桶 KRN 指定目标向量桶，vectorBucketName 与 vectorBucketKrn 严格二选一。同时提供返回 400 VectorBucketNameAndArnConflict，都不提供返回 400 VectorBucketInfoMissing

请求头

该接口仅使用公共请求头。

请求体

参数	是否必填	类型	说明
vectorBucketName	否，与 vectorBucketKrn 二选一	string	向量桶名称。3-63 字符，仅小写字母、数字和连字符（`-`），首尾不得为连字符。
vectorBucketKrn	否，与 vectorBucketName 二选一	string	向量桶 KRN，格式 `krn:ksc:ks3vectors:<region>:<accountId>:bucket/<bucketName>`。
prefix	否	string	仅返回索引名称以指定前缀开头的索引。最大 63 字符。
maxResults	否	integer	本页返回的最大条数，取值 1~500，默认 100。
nextToken	否	string	分页标记，从上一次响应中获取。最大 512 字符；不填表示从头开始列举。

响应

响应头

除了公共响应头外，返回 Content-Type: application/json。

响应体

名称	父节点	描述	类型
nextToken	无	下一页的分页标记。当本页返回条数达到 `maxResults` 时，响应可能包含该字段；返回条数小于 `maxResults` 或列表为空表示已列举完毕。	string
indexes	无	索引列表	array

节点 indexes 的内容：

名称	父节点	描述	类型
creationTime	indexes	索引创建时间（Unix 毫秒时间戳）	long
vectorBucketName	indexes	向量桶名称，例如 examplebucket-1250000000，长度限制3-63个字符	string
indexKrn	indexes	向量索引资源名称（KRN），格式 `krn:ksc:ks3vectors:<region>:<accountId>:bucket/<bucketName>/index/<indexName>`	string
indexName	indexes	索引名称，长度限制3-63个字符	string
dataType	indexes	向量数据类型，目前仅支持 `float32`	string
dimension	indexes	向量维度，取值 2~4096	integer
nextToken	indexes	下一页的分页标记。当本页返回条数达到 `maxResults` 时，响应可能包含该字段；返回条数小于 `maxResults` 或列表为空表示已列举完毕。	string
distanceMetric	indexes	距离度量函数，`euclidean` 或 `cosine`	string
metadataConfiguration	indexes	元数据配置。创建索引时未配置该字段时，返回项中不包含 `metadataConfiguration`	object
nonFilterableMetadataKeys	metadataConfiguration	不可用于筛选的元数据键列表，最多 10 个；每个 key 为 1-63 字符，以字母或下划线开头，仅允许字母、数字和下划线。	string[]

示例

请求示例

POST /ListIndexes HTTP/1.1
Host: ks3vectors-cn-beijing.ksyuncs.com
Authorization: authorization string
Date: Mon, 10 Dec 2025 12:49:14 GMT
Content-Type: application/json

{
  "vectorBucketName": "example-bucket",
  "prefix": "example",
  "maxResults": 100
}

响应示例

HTTP/1.1 200 OK
Content-Type: application/json
Date: Fri, 24 May 2025 11:59:51 GMT
Server: KS3
x-kss-request-id: 54a47bda18ac4e6e91de369add54218***
{
  "indexes": [
    {
      "indexKrn": "krn:ksc:ks3vectors:cn-beijing:103735000000:bucket/example-bucket/index/exampleindex",
      "vectorBucketName": "example-bucket",
      "indexName": "exampleindex",
      "creationTime": 1755127842368,
      "dataType": "float32",
      "dimension": 1024,
      "distanceMetric": "euclidean",
      "metadataConfiguration": {
        "nonFilterableMetadataKeys": ["key_c", "key_d"]
      }
    }
  ]
}

错误码

HTTP 状态码	错误码	描述	典型触发场景
400	ValidationException	请求参数不合法	`maxResults` 超出 1~500；`prefix` 超过 63 字符；`nextToken` 超过 512 字符或格式非法；桶标识同时提供或缺失。
403	AccessDeniedException	访问被拒绝	非桶拥有者且无 `ks3:ListIndexes` 权限。
404	NotFoundException	资源不存在	指定的向量桶不存在（`NoSuchBucket`）。
500	InternalServerException	服务内部错误	服务内部异常。

具体错误码通过响应头 x-kss-error-code 返回。

错误响应体格式如下：

{
  "message": "The indexName is invalid.",
  "fieldList": [
    {
      "path": "/indexName",
      "message": "..."
    }
  ]
}

fieldList 仅校验类错误（ValidationException）携带；其他错误只返回 message。

文档导读

上一篇：Get Index

下一篇：Delete Index

纯净模式常规模式

纯净模式

点击可全屏预览文档内容