金山云-文档中心-Get Index

对象存储(KS3)

查看更多结果

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

页面目录

全部展开全部收起

产品更新动态

未找到含该关键词的产品

文档中心

对象存储(KS3)

API文档

向量存储桶（KS3 Vectors）

索引相关

Get Index

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



描述

获取向量索引的详细信息，或确认该索引是否存在。使用此接口，您必须是这个 Bucket 的拥有者或拥有 ks3:GetIndex 权限。

调用Get Index时：

索引存在且有读取权限，返回 HTTP 状态码为200。

无索引读取权限，返回 HTTP 状态码为403。

索引不存在，返回 HTTP 状态码为404。

请求

请求语法

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

{
  "vectorBucketName": "string",
  "indexName": "string"
}

请求参数

该接口不使用请求参数。

请求头

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

请求体

获取向量桶时提交 application/json 请求数据，需指定向量桶名字和索引名字或者使用索引资源名称。

参数	是否必填	类型	说明
indexKrn	否，与 indexName + vectorBucketName 严格二选一	string	索引资源名称（KRN），格式 `krn:ksc:ks3vectors:<region>:<accountId>:bucket/<bucketName>/index/<indexName>`。
indexArn	否，与 indexName + vectorBucketName 严格二选一	string	AWS4 签名协议下使用的字段名；KS3 签名协议下使用 `indexKrn`。二者不要同时提供。
indexName	否，构成 name 组合时必填，与 indexKrn/indexArn 互斥	string	索引名称。3-63 字符，仅小写字母和数字，首字符必须是字母；不允许 `-`、`.`，不允许数字开头。
vectorBucketName	否，构成 name 组合时必填，与 indexKrn/indexArn 互斥	string	向量桶名称。3-63 字符，仅小写字母、数字和连字符（`-`），首尾不得为连字符。

响应

响应头

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

响应体

响应体内容的具体参数描述：

名称	父节点	描述	类型
index	无	保存 GET Index 结果的所有信息	Container

Container 节点 index 的内容：

名称	父节点	描述	类型
creationTime	index	索引创建时间（Unix 毫秒时间戳）	long
dataType	index	向量数据类型，默认值为 float32	string
dimension	index	向量维度，取值 2~4096。	integer
distanceMetric	index	相似性搜索的距离度量。可选值 euclidean（欧氏距离）或者 cosine（余弦距离）	string
indexKrn	index	向量索引资源名称（KRN），格式 `krn:ksc:ks3vectors:<region>:<accountId>:bucket/<bucketName>/index/<indexName>`	string
indexName	index	索引名称，长度限制3-63字符	string
metadataConfiguration	index	元数据配置。创建索引时未配置该字段时，响应中不返回 `metadataConfiguration`。	Container
vectorBucketName	index	向量桶名称	string

Container 节点 metadataConfiguration 的内容：

名称	父节点	描述	类型
nonFilterableMetadataKeys	metadataConfiguration	不可用于筛选的元数据键列表，最多 10 个；每个 key 为 1-63 字符，以字母或下划线开头，仅允许字母、数字和下划线。	string 数组

示例

请求示例

POST /GetIndex 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",
  "indexName": "exampleindex"
}

使用索引 KRN 时，请求体为：

{
  "indexKrn": "krn:ksc:ks3vectors:cn-beijing:103735000000:bucket/example-bucket/index/exampleindex"
}

响应示例

HTTP/1.1 200 OK
Content-Type: application/json
Date: Tue, 28 May 2025 03:16:12 GMT
Server: KS3
x-kss-request-id: 54a47bda18ac4e6e91de369add54218***

{
  "index": {
    "indexKrn": "krn:ksc:ks3vectors:cn-beijing:103735000000:bucket/example-bucket/index/exampleindex",
    "vectorBucketName": "example-bucket",
    "indexName": "exampleindex",
    "creationTime": 1755127842368,
    "dataType": "float32",
    "dimension": 1024,
    "distanceMetric": "cosine",
    "metadataConfiguration": {
      "nonFilterableMetadataKeys": ["key_c", "key_d"]
    }
  }
}

错误码

HTTP 状态码	错误码	描述	典型触发场景
400	ValidationException	请求参数不合法	`indexKrn`/`indexArn` 与 name 组合同时提供或都未提供；`indexName` 或 `vectorBucketName` 不符合命名规则；KRN 格式或 region 不合法。
403	AccessDeniedException	访问被拒绝	非桶拥有者且无 `ks3:GetIndex` 权限。
404	NotFoundException	资源不存在	指定的向量桶不存在（`NoSuchBucket`），或索引不存在（`NoSuchVectorIndex`）。
500	InternalServerException	服务内部错误	服务内部异常。

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

错误响应体格式如下：

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

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

文档导读

上一篇：Create Index

下一篇：List Indexes

纯净模式常规模式

纯净模式

点击可全屏预览文档内容