调用ListVectors接口列举向量索引中的所有向量数据。
权限说明
阿里云账号默认拥有全部权限。阿里云账号下的RAM用户或RAM角色默认没有任何权限,需要阿里云账号或账号管理员通过RAM Policy或Bucket Policy授予操作权限。
API | Action | 说明 |
ListVectors |
| 列举向量数据。 |
请求语法
POST /?listVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou.oss-vectors.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
Content-type: application/json
{
"indexName": "string",
"maxResults": int,
"nextToken": "string",
"returnData": boolean,
"returnMetadata": boolean,
"segmentCount": int,
"segmentIndex": int
}
请求头
此接口仅涉及公共请求头。更多信息,请参见公共HTTP头定义。
请求参数
名称 | 数据类型 | 是否必选 | 示例值 | 描述 |
indexName | 字符串 | 是 | vectorindex1 | 索引名称。 |
maxResults | 数值 | 否 | 500 | 每次返回的最大结果数,默认值500,最大为1000。 |
nextToken | 字符串 | 否 | CAESCG15aC1xxxxx | 查询凭证(Token),取值为上一次API调用返回的nextToken参数值。第一次调用此接口时,设置为空。参数长度为1~2048字节。 |
returnData | 布尔值 | 否 | false | 是否返回向量数据。取值:
|
returnMetadata | 布尔值 | 否 | false | 是否返回元数据。取值:
|
segmentCount | 数值 | 否 | 1 | 并行ListVectors时,用户可指定并行度,最大为16。串行时,设置为1。 |
segmentIndex | 数值 | 否 | 0 | 并行ListVectors时,分段的index必须小于segmentCount。 |
响应头
此接口仅涉及公共响应头。更多信息,请参见公共HTTP头定义。
响应元素
名称 | 数据类型 | 示例值 | 说明 |
nextToken | 字符串 | CAESCG15aC2xxxxx | 下一页查询凭证(Token)。如果为空,表示已列举完成。 |
vectors | 对象数组 | 不适用 | 返回向量列表。 |
key | 字符串 | doc-001 | 向量主键。 父节点:vectors |
data | 对象 | 不适用 | 向量数据(仅当returnData为true时返回)。 父节点:vectors |
metadata | 对象 | 不适用 | 元数据(仅当returnMetadata为true时返回)。 父节点:vectors |
示例
请求示例
POST /?listVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou.oss-vectors.aliyuncs.com
Date: Thu, 17 Apr 2025 01:33:47 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218
Content-type: application/json
{
"indexName": "vectorindex1",
"maxResults": 10,
"returnData": true,
"returnMetadata": true
}
返回示例
HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 01:33:47 GMT
Connection: keep-alive
Server: AliyunOSS
Content-type: application/json
{
"nextToken": "CAESCG15aC2xxxxx",
"vectors": [
{
"data": {
"float32": [0.1, 0.2, 0.3, 0.4, 0.5]
},
"key": "doc-001",
"metadata": {
"category": ["technology", "ai"],
"title": "Introduction to Vector Search"
}
},
{
"data": {
"float32": [0.2, 0.3, 0.4, 0.5, 0.6]
},
"key": "doc-002",
"metadata": {
"category": ["science"],
"title": "Advanced Vector Operations"
}
}
]
}
错误码
错误码 | HTTP状态码 | 描述 |
VectorIndexParameterInvalid | 400 | 请求中提供的向量索引参数不合法。 |
MalformedJson | 400 | 请求体中的 JSON 格式不符合规范。 |
AccessDenied | 403 | 返回该错误的可能原因如下:
|
NoSuchVectorIndex | 404 | 指定的向量索引不存在。 |
QpsLimitExceeded | 503 | QPS 限流(请求速率受限)。 |