Object Storage Service:OSS における S3 および S3 Vectors API：サポートされるオペレーションと制限

汎用バケットと互換性のある S3 API オペレーション

次の表に、OSS の汎用バケットと互換性のある、S3 のバケットオペレーション、オブジェクトオペレーション、およびマルチパートオペレーションを示します。

汎用バケットと S3 の違い

このセクションでは、OSS の汎用バケットと S3 の違いについて説明します。

• リクエスト形式

  Amazon S3 は、仮想ホスト形式とパス形式の 2 つのリクエストアドレス指定形式をサポートしています。仮想ホスト形式のリクエストでは、バケット名がエンドポイントのサブドメインとして使用されますが、パス形式のリクエストでは、バケット名が URL パスに配置されます。セキュリティ上の理由から、OSS は仮想ホスト形式のみをサポートしています。したがって、S3 から OSS に移行した後、すべてのクライアントアプリケーションと S3 互換ツールは、仮想ホスト形式のリクエストを使用するように設定する必要があります。そうしないと、アクセスが拒否されます。

• アクセス制御リスト (ACL) の定義

  ACL の定義は OSS と S3 で異なります。違いは次の表のとおりです。

  レベル	権限	S3	OSS
  バケット	READ	バケットを一覧表示する権限。	バケット内のオブジェクトにオブジェクト権限が設定されていない場合、そのオブジェクトに対して読み取り操作のみを実行できます。
  	WRITE	バケット内のオブジェクトの書き込み、または上書きを行う権限。	書き込み対象のオブジェクトが指定されたバケットに存在しない場合、そのオブジェクトはバケット内に作成されます。 書き込み対象のオブジェクトが指定されたバケットに存在し、既存のオブジェクトに権限が設定されていない場合、既存のオブジェクトは上書きできます。 InitiateMultipartUpload を使用してオブジェクトをアップロードします。
  	READ_ACP	バケットの ACL を読み取る権限。	バケット所有者と承認された RAM ユーザーのみが、バケットの ACL を読み取ることができます。
  	WRITE_ACP	バケットの ACL を設定する権限。	バケット所有者と承認された RAM ユーザーのみが、バケットの ACL を設定できます。
  オブジェクト	READ	オブジェクトを読み取る権限。	オブジェクトを読み取る権限。
  	WRITE	N/A	オブジェクトを上書きする権限。
  	READ_ACP	オブジェクトの ACL を読み取る権限。	バケット所有者と承認された RAM ユーザーのみが、オブジェクトの ACL を読み取ることができます。
  	WRITE_ACP	オブジェクトの ACL を設定する権限。	バケット所有者と承認された RAM ユーザーのみが、オブジェクトの ACL を設定できます。

  重要

  OSS は、S3 の次の ACL モードのみをサポートしています：private、public-read、public-read-write。

• ストレージクラス

  OSS と S3 のストレージクラスは 1 対 1 で対応しておらず (OSS は 5 種類、S3 は 7 種類の主要なストレージクラスを提供)、最短ストレージ期間やアクセス方法などの機能が異なります。要件に基づいて OSS オブジェクトのストレージクラスを変換できます。主な対応関係と違いは次の表のとおりです。

  OSS ストレージクラス	対応する S3 ストレージクラス	主な違い
  Standard	STANDARD	最短ストレージ期間：OSS も S3 も要件はありません。 アクセス方法：どちらもリアルタイムアクセスをサポートしています。
  Infrequent Access	STANDARD_IA ONEZONE_IA	マッピング：OSS のゾーン冗長 IA は STANDARD_IA に、ローカル冗長 IA は ONEZONE_IA に対応します。 最短ストレージ期間：どちらも 30 日間です。 アクセス方法：どちらもリアルタイムアクセスをサポートしており、データ取得料金が発生します。
  Archive	GLACIER_IR GLACIER (Flexible)	最短ストレージ期間：OSS は 60 日間、S3 は 90 日間です。 アクセス方法：OSS では復元操作 (約 1 分) が必要ですが、アーカイブオブジェクトへのリアルタイムアクセスを有効にすることもできます。S3 GLACIER_IR はミリ秒レベルのリアルタイムアクセスを提供しますが、GLACIER (Flexible) では復元操作 (Expedited：1～5 分、Standard：3～5 時間、Bulk：5～12 時間) が必要です。
  コールドアーカイブ	DEEP_ARCHIVE	最短ストレージ期間：どちらも 180 日間です。 アクセス方法：どちらも復元操作が必要です。OSS の復元は、高優先度で約 1 時間、標準で 2～5 時間、バッチで 5～12 時間です。S3 ストレージクラスの中では、GLACIER (Flexible) のみがこの復元時間帯に該当します。一方、DEEP_ARCHIVE は Standard で 12 時間以下 (Batch 9～12 時間)、Bulk で 48 時間以下が必要です。
  ディープコールドアーカイブ	対応するストレージクラスはありません	OSS 独自の、非常にコールドなデータ向けのストレージクラスです。AWS には DEEP_ARCHIVE よりもコールドなストレージクラスはありません (対応する S3 ストレージクラスはありません)。 最短ストレージ期間：OSS は 180 日間です (対応する S3 ストレージクラスはありません)。 アクセス方法：OSS では復元操作が必要です。高優先度で約 12 時間、標準で約 48 時間です (S3 ストレージクラスの中では、DEEP_ARCHIVE のみがこの復元時間帯に該当します)。

  説明

  さらに、S3 は専用の INTELLIGENT_TIERING ストレージクラスを提供しており、アクセス頻度に基づいてオブジェクトを複数のアクセス階層間で自動的に移動します。OSS は専用の INTELLIGENT_TIERING ストレージクラスを提供していませんが、ライフサイクルルールを使用することで同様の自動階層化を実現できます。

  バケットでアーカイブオブジェクトへのリアルタイムアクセスが有効になっていない場合、アクセスする前にまずバケット内のアーカイブオブジェクトを復元する必要があります。OSS は、S3 API でオブジェクトに設定された復元状態の期間を無視します。デフォルトでは、復元状態は 1 日間持続し、最大 7 日間まで延長できます。その後、オブジェクトは凍結状態になります。

• ETag

  • PUT メソッドを使用してオブジェクトがアップロードされる場合、OSS オブジェクトの ETag と Amazon S3 オブジェクトの ETag では、大文字と小文字の区別が異なります。OSS オブジェクトの ETag は大文字で、Amazon S3 オブジェクトの ETag は小文字です。クライアントが ETag を使用してコンテンツを検証する場合、エラーを防ぐために、大文字と小文字を区別しないようにクライアントを設定してください。

  • マルチパートアップロードメソッドを使用してオブジェクトをアップロードする場合、OSS は S3 とは異なる方法で ETag 値を計算します。

ベクターバケットと互換性のある S3 Vectors API オペレーション

OSS Vectors のベクターバケットは、Amazon S3 Vectors プロトコルと互換性があります。アプリケーションを書き換える必要はありません。AWS SDK の S3 Vectors クライアントのエンドポイントをベクターバケットのアクセスドメイン名に指定することで、ベクターバケット、ベクターインデックス、ベクターデータを管理し、類似性クエリを実行できます。OSS Vectors の詳細については、「OSS Vectors」をご参照ください。ネイティブの OSS Vectors API の詳細については、「OSS Vector operations」をご参照ください。

AWS SDK を使用してベクターバケットにアクセスするには、クライアントを次のように設定します。

• サービス名： s3vectors。リクエストは AWS 署名バージョン 4 を使用して署名されます。署名は SDK が処理するため、追加の設定は不要です。

• パブリックエンドポイント： https://$bucketname-$uid.$regionID.oss-vectors.aliyuncs.com

• 内部エンドポイント： https://$bucketname-$uid.$regionID-internal.oss-vectors.aliyuncs.com

• リージョン： ベクターバケットが存在するリージョンの ID。例： cn-hangzhou。

次の表に、ベクターバケットがサポートする S3 Vectors API オペレーションと、対応する OSS Vectors API オペレーションを示します。

以下の S3 Vectors オペレーションはサポートされていません。これらのオペレーションのいずれかを呼び出すと、405 MethodNotAllowed エラーが返されます: UpdateIndexMode、PutVectorBucketDefaultIndexMode、TagResource、UntagResource、および ListTagsForResource。

以下のサンプルコードは、Python (Boto3) を使用して S3 Vectors API 経由でベクトルインデックスを作成し、ベクトルデータを書き込み、ベクトルをクエリする方法を示しています。コードを実行する前に、pip install -U boto3 を実行して S3 Vectors クライアントを含む Boto3 バージョンをインストールし、お使いのアクセスキーペアを環境変数に格納してください。

import os
import boto3

# ベクターバケットのアクセスドメイン名。形式は https://$bucketname-$uid.$regionID.oss-vectors.aliyuncs.com です。
client = boto3.client(
    "s3vectors",
    region_name="cn-hangzhou",
    endpoint_url="https://examplebucket-123***456.cn-hangzhou.oss-vectors.aliyuncs.com",
    aws_access_key_id=os.environ.get("OSS_ACCESS_KEY_ID"),
    aws_secret_access_key=os.environ.get("OSS_ACCESS_KEY_SECRET"),
)

# ベクターインデックスを作成します。インデックス名には英字と数字のみを使用でき、先頭は英字である必要があります。
client.create_index(
    vectorBucketName="examplebucket",
    indexName="exampleindex",
    dataType="float32",
    dimension=4,
    distanceMetric="cosine",
)

# ベクターデータを書き込みます。
client.put_vectors(
    vectorBucketName="examplebucket",
    indexName="exampleindex",
    vectors=[
        {
            "key": "key1",
            "data": {"float32": [0.1, 0.2, 0.3, 0.4]},
            "metadata": {"genre": "doc"},
        }
    ],
)

# ベクターデータをクエリします。
response = client.query_vectors(
    vectorBucketName="examplebucket",
    indexName="exampleindex",
    queryVector={"float32": [0.1, 0.2, 0.3, 0.4]},
    topK=3,
    returnDistance=True,
    returnMetadata=True,
)
print(response["vectors"])

ベクターバケットと S3 Vectors の違い

S3 Vectors から OSS Vectors に切り替える場合は、次の違いに注意してください：

• リソースのアドレス指定方法

  S3 Vectors は固定のサービスエンドポイントを使用し、リクエストボディの vectorBucketName または vectorBucketArn パラメーターでベクターバケットを識別します。OSS Vectors はサードレベルドメイン名からベクターバケットを解決し、それに対してリクエストボディを検証します。リクエストボディの vectorBucketName または vectorBucketArn パラメーターが、ドメイン名内のベクターバケットと一致しない場合、400 ValidationException エラーが返されます。

• ARN 形式

  OSS Vectors は Alibaba Cloud のリソース名形式を使用します。ベクターバケットの ARN は acs:ossvector:$regionID:$uid:$bucketname、ベクターインデックスの ARN は acs:ossvector:$regionID:$uid:$bucketname/$indexname です。arn:aws:s3vectors:* 形式はサポートされていません。ARN パラメーターはすべてのリクエストでオプションです。vectorBucketName および indexName パラメーターを使用して、リソースを名前で指定することを推奨します。

• 命名規則

  ベクターバケット名は 3～32 文字 (S3 Vectors では 3～63 文字) で、小文字、数字、ハイフン (-) のみ使用できます。先頭または末尾にハイフン (-) は使用できません。ベクターインデックス名は 1～63 文字で、英字と数字のみ使用でき、先頭は英字である必要があります。S3 Vectors では、インデックス名は 3～63 文字で、小文字、数字、ハイフン (-)、ピリオド (.)、およびアンダースコア (_) を使用できます。そのため、S3 Vectors から切り替える場合は、名前にハイフン (-)、アンダースコア (_)、またはピリオド (.) を含むベクターインデックス名を変更する必要があります。

• サーバー側の暗号化

  OSS Vectors はサーバー側の暗号化をサポートしていません。CreateVectorBucket および CreateIndex リクエストの encryptionConfiguration パラメーターは解析されますが無視され、エラーは返されません。GetVectorBucket および GetIndex のレスポンスには、このパラメーターは含まれません。

• リソースタグ

  OSS Vectors はリソースタグをサポートしていません。CreateVectorBucket リクエストの tags パラメーターは解析されますが無視されます。また、TagResource、UntagResource、ListTagsForResource オペレーションは 405 MethodNotAllowed エラーを返します。

• 拡張モード (Enhanced Mode) (メタデータの事前フィルタリング) の非サポート

  S3 Vectors では、メタデータの事前フィルタリング向けに ENHANCED インデックスモードが追加され、元のモードは CLASSIC に名称変更されました。OSS Vectors はこのモードをサポートしていません。関連するオペレーションとパラメーターの動作は次のとおりです：

  • UpdateIndexMode および PutVectorBucketDefaultIndexMode オペレーションはサポートされておらず、405 MethodNotAllowed エラーを返します。

  • QueryVectors は queryMode パラメーターをサポートしていません。このパラメーターは S3 Vectors ではオプションです。CLASSIC または ENHANCED を設定すると、メッセージ Unknown field: queryMode in request. を伴う 400 ValidationException エラーが返されます。通常どおりクエリを実行するには、このパラメーターを省略してください。

  • ENHANCED モードでのみ使用できる $startsWith フィルターオペレーターはサポートされていません。メッセージ Invalid filter operation: $startsWith. を伴う 400 ValidationException エラーが返されます。

  • GetIndex のレスポンスには indexMode が含まれず、GetVectorBucket のレスポンスには defaultIndexMode が含まれません。

  メタデータの事前フィルタリングまたはハイブリッド検索が必要な場合は、OSS Vectors のフュージョンモードインデックスを使用してください。詳細については、「OSS Vectors」をご参照ください。

• S3 Vectors にはない機能

  ベクターバケットのアクセスログ記録 (PutVectorBucketLogging、GetVectorBucketLogging、DeleteVectorBucketLogging) と、ハイブリッド検索を使用するフュージョンモードインデックス (PutVectorIndexFusion、QueryVectorsFusion) は、S3 Vectors に相当するオペレーションがありません。これらの機能については、ネイティブの OSS Vectors API を呼び出してください。S3 Vectors API の CreateIndex は、標準モードのインデックスを作成します。

• エラーレスポンス

  S3 互換リクエストでは、JSON 形式でエラー情報が返され、例外タイプはレスポンスヘッダー x-amzn-errortype に返されます。次の表に、一般的な例外タイプを示します。

  HTTP ステータスコード	例外タイプ	主な原因
  400	ValidationException	リクエストパラメーターが無効です。たとえば、ARN 形式が無効、インデックス名が命名規則に準拠していない、またはリクエストボディ内のベクターバケットがドメイン名内のベクターバケットと一致しない場合です。
  400	SerializationException	リクエストボディが仕様に準拠していない、または JSON ボディではありません。たとえば、リクエストボディが有効な JSON ではありません。エラーメッセージは Failed to parse request. です。
  403	AccessDeniedException	アクセスキー ID が存在しない、署名検証に失敗した、または必要な権限がありません。
  404	NotFoundException	指定されたベクターバケットまたはベクターインデックスが存在しません。
  405	MethodNotAllowed	このオペレーションは OSS Vectors でサポートされていません。たとえば、オペレーションがリソースタグオペレーションの場合です。
  409	ConflictException	ベクターバケットまたはベクターインデックスの名前がすでに存在するか、空ではないベクターバケットを削除しようとした場合です。