ListVectors - Object Storage Service

調用ListVectors介面列舉向量索引中的所有向量資料。

許可權說明

阿里雲帳號預設擁有全部許可權。阿里雲帳號下的RAM使用者或RAM角色預設沒有任何許可權，需要阿里雲帳號或帳號管理員通過RAM Policy或Bucket Policy授予操作許可權。

API	Action	說明
ListVectors	`oss: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	是否返迴向量資料。取值： true false（預設值）
returnMetadata	布爾值	否	false	是否返回中繼資料。取值： true 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 限流（請求速率受限）。