オブジェクトへの注釈
注釈を使用して、名前付きデータペイロードを Amazon S3 オブジェクトにアタッチします。各注釈は、オブジェクト自体を変更せずに作成、取得、一覧表示、削除できる、1 バイト～1 MiB のサイズのカスタムメタデータペイロードです。
最大 1,000 個の注釈をオブジェクトバージョンに関連付けることができます。各注釈には一意の名前があり、AI 生成ラベル、ドキュメントコンテキスト、処理結果、コンプライアンスレコードなどの構造化データを保存できます。
一般的なユースケースとして、機械学習の推論結果、AI 生成の埋め込み、コンテンツモデレーションラベル、ドキュメント分類出力、データリネージュと監査証跡、PII フラグや保持ポリシーなどのコンプライアンスラベル、医療画像メタデータ、デジタルアセット権利情報、ETL パイプラインステータスを、ソースオブジェクトとともに保存します。
注釈は専用の API オペレーションを使用して管理するため、メタデータを追加または更新するためにオブジェクトを再アップロードする必要はありません。
S3 メタデータ設定の一部として注釈テーブルを有効にし、Athena やその他の分析サービスを使用して注釈データを大規模にクエリできます。S3 メタデータは、Amazon S3 が自動的に最新の状態に保つフルマネージド Apache Iceberg テーブルに注釈データを保存します。詳細については、「S3 メタデータテーブルを使用したデータの検出」を参照してください。
注釈は、すべての商用 AWS リージョンと中国リージョン (北京および寧夏) でご利用可能です。注釈は、中東 (アラブ首長国連邦) および中東 (バーレーン) リージョンではご利用いただけません。S3 メタデータ注釈テーブルは、S3 メタデータが利用可能なすべてのリージョンで使用できます。
注釈を使用すべきタイミングと、オブジェクトタグを使用すべきタイミングの比較
次の比較を使用して、注釈またはオブジェクトタグのどちらがユースケースに最適かを判断してください。
| 特性 | オブジェクトタグ | 注釈 |
|---|---|---|
| オブジェクトごとの最大数 | オブジェクトバージョンあたり 10 | オブジェクトバージョンあたり 1,000 |
| 最大サイズ | 128 文字 (キー) + 256 文字 (値) | 512 バイト (名前) + 1 MiB (ペイロード) |
| データ形式 | キー値文字列のペア | UTF-8 テキスト (JSON、XML、YAML など) |
| 変更可能性 | はい (PutObjectTagging) | はい (PutObjectAnnotation) |
| アップロード時に設定 | はい (PutObject、POST) | いいえ (PutObjectAnnotation のみ、アップロード後) |
構造化データ (JSON や XML など)、256 文字を超えるペイロード、またはオブジェクトごとに 10 個を超えるメタデータエントリを保存する必要がある場合は、注釈を選択します。IAM ポリシー統合、Amazon S3 ライフサイクルルールのフィルタリング、またはコスト配分レポートが必要な場合は、オブジェクトタグを選択します。
注釈の API オペレーション
Amazon S3 は、注釈を操作するために次の API オペレーションをサポートしています。
-
PutObjectAnnotation – オブジェクトの注釈を作成または上書きします。リクエストで注釈名とペイロードを指定します。
-
GetObjectAnnotation – 特定の注釈のペイロードを名前で返します。
-
ListObjectAnnotations – オブジェクトの注釈のリストを返します。レスポンスには、各注釈の名前、サイズ、ETag、および最終更新日が含まれます。
-
DeleteObjectAnnotation – 特定の注釈を名前で削除します。
Amazon S3 では、以下の API オペレーションでも注釈がサポートされています。
-
CopyObject – デフォルトでは、ソースオブジェクトから注釈をコピーします。
x-amz-annotation-directiveヘッダーを指定して、注釈をコピー (COPY) するか除外 (EXCLUDE) するかを制御できます。 -
UpdateBucketMetadataAnnotationTableConfiguration – S3 メタデータ設定の注釈テーブルを有効または無効にします。
-
CreateBucketMetadataConfiguration – S3 メタデータ設定を作成するときに、注釈テーブルを有効にする新しい
AnnotationTableConfigurationパラメータを受け入れます。 -
GetBucketMetadataConfiguration – レスポンスで
AnnotationTableConfigurationResultを返します。これは、注釈テーブルの現在のステータスを示します。
注釈の制限
各オブジェクトバージョンは、最大 1,000 個の注釈をサポートします。オブジェクトバージョンに関連付けられている注釈には、一意の注釈名が必要です。以下の制限が適用されます。
-
注釈名の長さは最大 512 バイト (UTF-8) で、以下の命名規則に従います。
-
注釈ペイロードのサイズは 1 バイト～1 MiB にする必要があります。
-
オブジェクトあたりの注釈ストレージの合計は、最大 1 GiB (各 1 MiB で 1,000 個の注釈) です。
-
サポートされているチェックサムアルゴリズムは、CRC32、CRC32C、CRC64NVME、SHA1、SHA256、SHA512、XXHASH64、XXHASH3、XXHASH128 です。
注釈の命名規則
注釈名は、以下の要件を満たしている必要があります。
-
1～512 バイトの長さにする必要があります。
-
文字 (任意の言語)、数字 (0～9)、アンダースコア (
_)、ピリオド (.)、およびハイフン (-) のみを含めることができます。 -
awsまたはs3(大文字と小文字を区別しません) で始めることはできません。例えば、aws、AWS、s3、S3はすべて予約済みプレフィックスです。 -
空にすることも、空白のみで構成することもできません。
暗号化
注釈は、親オブジェクトと同じ暗号化設定を使用して、保管時に自動的に暗号化されます。暗号化タイプは、バケットのデフォルトではなく、親オブジェクトから継承されます。
-
SSE-S3 – 親オブジェクトが Amazon S3 マネージドキーによるサーバー側の暗号化 (SSE-S3) を使用している場合、注釈は SSE-S3 で暗号化されます。親オブジェクトにサーバー側の暗号化が設定されていない場合、注釈はデフォルトで SSE-S3 で暗号化されます。
-
SSE-KMS – 親オブジェクトが AWS KMS キーによるサーバー側の暗号化 (SSE-KMS) を使用している場合、注釈は同じ KMS キーで暗号化されます。これは、カスタマーマネージドキーと AWS マネージドキーの両方に該当します。S3 バケットキーがサポートされています。
-
DSSE-KMS – 親オブジェクトが AWS KMS キーによる二層式サーバー側の暗号化 (DSSE-KMS) を使用している場合、注釈は同じキーを使用して DSSE-KMS で暗号化されます。
-
SSE-C – お客様が用意したキーを使用したサーバー側の暗号化 (SSE-C) では、注釈はサポートされていません。SSE-C で暗号化されたオブジェクトへの注釈の追加を試みると、Amazon S3 はエラーを返します。
チェックサム
PutObjectAnnotation を使用して注釈をアップロードする場合、チェックサムを指定してデータの整合性を確認できます。注釈のチェックサムアルゴリズムは、親オブジェクトのチェックサムアルゴリズムから独立しています。
CopyObject を使用してオブジェクトをコピーすると、Amazon S3 はソースから注釈チェックサム値を保持します。コピーリクエストで別のチェックサムアルゴリズムを指定すると、新しいアルゴリズムはオブジェクトとその注釈の両方に適用されます。
サポートされているアルゴリズムは、CRC32、CRC32C、CRC64NVME、SHA1、SHA256、SHA512、XXHASH64、XXHASH3、XXHASH128 です。
注釈に指定されたチェックサムアルゴリズムまたはチェックサム値がない場合、Amazon S3 は CRC-64/NVME アルゴリズムを使用して注釈のチェックサム値を計算します。
バージョニングの動作
注釈は、特定のオブジェクトバージョンにアタッチされます。
1 つのオブジェクトバージョンの注釈は、同じオブジェクトの他のバージョンの注釈とは無関係です。新しいバージョンを作成しても、以前のバージョンの注釈はコピーされません。あるバージョンで注釈を削除または追加しても、他のバージョンの注釈には影響しません。オブジェクトを上書きすると、その注釈は新しいバージョンの注釈に置き換えられます (上書きがない場合、注釈は実質的に削除されます)。
注釈を追加、更新、または削除しても、親オブジェクトの ETag は変更されません。
バージョン管理されていないバケットでオブジェクトを削除または上書きすると、そのバケットで注釈が削除されます。
バージョンバケットでは、以下の動作が適用されます。
-
単純な DELETE リクエスト (バージョン ID を指定しない) では、削除マーカーが作成されますが、基になるバージョンの注釈は保持されます。
-
特定のバージョン ID を削除すると、そのバージョンと関連するすべての注釈が削除されます。
-
注釈は個別にバージョニングされません。注釈を同じ名前で上書きすると、Amazon S3 は新しいオブジェクトバージョンを作成することなく、以前の値を置き換えます。
重要
注釈の削除は永続的で、元に戻すことはできません。バージョニングされたバケットでも同様です。バージョニングされたバケットのオブジェクトとは異なり、注釈には削除マーカーやバージョン履歴はありません。注釈を削除した場合、復元することはできません。
コピーの動作と整合性
CopyObject API を使用してオブジェクトをコピーする場合 (5 GiB 未満のオブジェクトの場合)、Amazon S3 は 1 回の操作でオブジェクトとともに注釈をコピーします。
マルチパートアップロードを使用してオブジェクトをコピーする場合 (例えば、AWS CLI または AWS SDK が約 8 MB を超えるオブジェクトに対して Transfer Manager を使用する場合)、注釈はデフォルトではコピーされません。注釈を含めるには、--copy-props all または同等の SDK 設定で AWS CLI を指定します。このオプトインにより、SDK はソースの注釈を読み取り、マルチパートアップロードを完了し、各注釈をターゲットに書き込みます。アップロードの完了と最後の注釈の書き込みの間に、ターゲットオブジェクトはすべての注釈なしで存在します。
考慮事項
-
注釈を
PutObjectまたはマルチパートアップロードリクエストの一部として追加することはできません。オブジェクトに注釈を追加するには、オブジェクトのアップロード後にPutObjectAnnotationを呼び出します。注釈付きの既存のオブジェクトを新しい場所にコピーするには、デフォルトの注釈ディレクティブでCopyObjectを使用します。 -
多くのオブジェクトに注釈を一括で追加または更新するには、バッチオペレーションを使用して、各オブジェクトで
PutObjectAnnotationを呼び出す Lambda 関数を呼び出します。詳細については、「AWS Lambda 関数の呼び出し」を参照してください。 -
S3 インベントリレポート、API Gateway、S3 Storage Lens、Amazon S3 File Gateway、Amazon FSx、S3 on Outposts、S3 Express One Zone (ディレクトリバケット)、および Amazon S3 Files の各機能では、注釈はサポートされていません。
-
上書きされていないオブジェクトの最新バージョンに注釈を書き込むには、
PutObjectAnnotationまたはDeleteObjectAnnotationでx-amz-object-if-match条件付きヘッダーを使用します。このヘッダーは、親オブジェクトの ETag を検証して、呼び出し元が最後に読み取ってからオブジェクトが上書きされていないことを確認します。タグまたは注釈を追加しても、ETag は変更されません。 -
別の注釈の有無に応じて注釈を条件付きで追加することはできません。
x-amz-object-if-matchヘッダーは、注釈の状態ではなく、親オブジェクトの ETag のみを検証します。 -
注釈ペイロードは、有効な UTF-8 エンコードテキストである必要があります。バイナリデータを保存するには、注釈を記述する前に Base64 でデータをエンコードします。
-
オブジェクトを最初に復元することなく、S3 Glacier や S3 Glacier Deep Archive など、任意のストレージクラスのオブジェクトに対して注釈 API オペレーション (
PutObjectAnnotation、GetObjectAnnotation、ListObjectAnnotations、DeleteObjectAnnotation) を呼び出すことができます。
追加の設定
このセクションでは、注釈と他の設定との関連について説明します。
レプリケーション
バケットに S3 レプリケーションを設定している場合、Amazon S3 は注釈を自動的にレプリケートします。各注釈は個別にレプリケートされます。詳細については、「Amazon S3 がレプリケートするもの」を参照してください。
注釈をレプリケートするには、レプリケーション IAM ロールのソースバケットのアクセス許可に s3:GetObjectVersionAnnotationForReplication を追加します。詳細については、「ライブレプリケーションのアクセス許可の設定」を参照してください。
オブジェクトレプリケーションの許可中に注釈のレプリケーションを防ぐには、レプリケーションロールポリシーに s3:ReplicateObjectAnnotation の拒否ステートメントを追加します。オブジェクトレプリケーションは成功し続け、注釈レプリケーションのみがブロックされます。
イベント通知
Amazon S3 は、注釈の作成、更新、または削除時にイベント通知を送信できます。以下のイベントタイプを設定できます。
-
s3:ObjectAnnotation:Put– 注釈が作成または更新されたときに送信されます。 -
s3:ObjectAnnotation:Delete– 注釈が削除されたときに送信されます。
詳細については、「イベント通知のタイプおよび送信先」を参照してください。
