GetVectors - Object Storage Service - Alibaba Cloud ドキュメントセンター

GetVectors API を呼び出して、キーを指定して特定のベクトルデータを取得します。

権限

Alibaba Cloud アカウントはデフォルトですべての権限を持ちます。ただし、RAM ユーザーおよび RAM ロールはデフォルトで権限を持ちません。この操作を実行するには、Alibaba Cloud アカウントまたは管理者が、RAM ポリシーまたはバケットポリシーを使用して権限を付与する必要があります。

API	Action	説明
GetVectors	`oss:GetVectors`	ベクトルデータを取得します。

リクエスト構文

POST /?getVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou.oss-vectors.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
Content-type: application/json

{
   "indexName": "string",
   "keys": [string, string, string],
   "returnData": boolean,
   "returnMetadata": boolean
}

リクエストヘッダー

この操作では、共通のリクエストヘッダーのみを使用します。詳細については、「共通 HTTP ヘッダー定義」をご参照ください。

リクエストパラメーター

名前	データ型	必須	例	説明
indexName	文字列	はい	vectorindex1	インデックス名です。
keys	文字列配列	はい	["doc-001", "doc-002"]	クエリ対象のベクトルのプライマリキーです。重複するプライマリキーも許容されます。制限事項は以下のとおりです。キー数：1～100 キー長：1～1024 文字
returnData	ブール値	いいえ	false	ベクトルデータを返す。値： true false（デフォルト）
returnMetadata	ブール値	いいえ	false	メタデータを応答に含めるかどうかを指定します。有効な値は以下のとおりです。 true false（デフォルト）

応答ヘッダー

この操作では、共通の応答ヘッダーのみが返されます。詳細については、「共通 HTTP ヘッダー」をご参照ください。

応答要素

名前	データ型	例	説明
vectors	オブジェクト配列	-	返されたベクトルのリストです。クエリ対象のプライマリキーが存在しない場合でもエラーは発生せず、そのキーに対応する結果は応答に含まれません。
key	文字列	doc-001	ベクトルのプライマリキーです。プライマリキーによるクエリにおいて、リクエスト内のキーに対応するベクトルが存在しない場合でもエラーは報告されません。応答には存在するベクトルのみが含まれ、該当キーのデータは含まれません。親ノード：vectors
data	オブジェクト	-	ベクトルデータ（returnData が true の場合にのみ返されます）。親ノード：vectors
metadata	オブジェクト	-	メタデータ（returnMetadata が true の場合にのみ返されます）。親ノード：vectors

例

リクエストの例

POST /?getVectors 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",
   "keys": ["doc-001", "doc-002"],
   "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

{
   "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"
         }
      }
   ]
}

SDK

以下の SDK で GetVectors 操作がサポートされています。

コマンドラインツール ossutil

GetVectors 操作に対応する ossutil コマンドの詳細については、「get-vectors」をご参照ください。

エラーコード

エラーコード	HTTP ステータスコード	説明
VectorIndexParameterInvalid	400	リクエストで指定されたベクトルインデックスパラメーターが無効です。
MalformedJson	400	リクエストボディの JSON 形式が無効です。
AccessDenied	403	このエラーが発生する可能性のある原因は以下のとおりです。リクエストの送信時に認証情報が提供されていません。必要な操作権限が付与されていません。
NoSuchVectorIndex	404	指定されたベクトルインデックスが存在しません。
QpsLimitExceeded	503	QPS 制限を超えました（リクエスト頻度が制限されています）。