View a markdown version of this page

註釋您的物件 - Amazon Simple Storage Service
何時使用註釋與物件標籤註釋的 API 操作註釋限制註釋命名規則加密檢查總和版本控制行為複製行為和一致性考量事項其他組態

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

註釋您的物件

使用註釋將具名資料承載連接到 Amazon S3 物件。每個註釋都是大小介於 1 位元組和 1 MiB 之間的自訂中繼資料承載，您可以建立、擷取、列出和刪除，而無需修改物件本身。

您最多可以將 1，000 個註釋與 物件版本建立關聯。每個註釋都有唯一的名稱，可以存放結構化資料，例如 AI 產生的標籤、文件內容、處理結果或合規記錄。

常見的使用案例包括儲存機器學習推論結果、AI 產生的內嵌、內容管制標籤、文件分類輸出、資料歷程和稽核線索、PII 標記或保留政策等合規標籤、醫療影像中繼資料、數位資產權利資訊，以及來源物件旁的 ETL 管道狀態。

您可以使用專用 API 操作來管理註釋，因此您不需要重新上傳物件來新增或更新中繼資料。

您可以在 S3 中繼資料組態中啟用註釋資料表，以使用 Athena 和其他分析服務大規模查詢註釋資料。S3 Metadata 會將註釋資料存放在 Amazon S3 自動保持最新狀態的全受管Apache Iceberg資料表中。如需詳細資訊，請參閱S3 Metadata 資料表探索您的資料。

註釋適用於所有商業 AWS 區域和中國區域 （北京和寧夏）。中東 （阿拉伯聯合大公國） 和中東 （巴林） 區域不提供註釋。S3 Metadata 註釋資料表可在可使用 S3 Metadata 的所有區域中使用。

何時使用註釋與物件標籤

使用以下比較來判斷註釋或物件標籤是否適合您的使用案例。

特性 物件標籤 註釋
每個物件的上限 每個物件版本 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 – 接受新AnnotationTableConfiguration參數，以在建立 S3 中繼資料組態時啟用註釋資料表。

  • GetBucketMetadataConfiguration – 在回應AnnotationTableConfigurationResult中傳回，指出註釋資料表的目前狀態。

註釋限制

每個物件版本最多支援 1，000 個註釋。與物件版本相關聯的註釋必須具有唯一的註釋名稱。適用下列限制：

  • 根據以下命名規則，註釋名稱的長度最多可達 512 個位元組 (UTF-8)。

  • 註釋承載的大小必須介於 1 位元組和 1 MiB 之間。

  • 每個物件的總註釋儲存體最多可達 1 GiB (1，000 個註釋，每個註釋 1 MiB)。

  • 支援的檢查總和演算法：CRC32、CRC32C、CRC64NVME、SHA1、SHA256、SHA512、XXHASH64、XXHASH3、XXHASH128。

註釋命名規則

註釋名稱必須符合下列要求：

  • 長度必須介於 1 到 512 個位元組之間。

  • 只能包含下列字元：字母 （任何語言）、數字 (0-9)、底線 (_)、句號 (.) 和連字號 ()-。

  • 開頭不可為 aws或 s3（不區分大小寫）。例如，aws、s3、 AWS和 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 演算法來計算註釋的檢查總和值。

版本控制行為

註釋會連接到特定的物件版本。

一個物件版本的註釋與相同物件的其他版本上的註釋無關。建立新版本不會複製先前版本的註釋。刪除或新增某個版本的註釋不會影響其他版本的註釋。覆寫物件會將其註釋取代為新版本具有的任何註釋 （如果沒有，則有效地刪除它們）。

新增、更新或移除註釋並不會修改父物件的 ETag。

在非版本控制的儲存貯體中，如果您刪除或覆寫物件，則會一併刪除註釋。

在版本控制的儲存貯體中，適用下列行為：

  • 簡單 DELETE 請求 （不指定版本 ID) 會建立刪除標記，但會保留基礎版本的註釋。

  • 刪除特定版本 ID 會刪除該版本和所有相關聯的註釋。

  • 註釋不會獨立版本化。當您以相同名稱覆寫註釋時，Amazon S3 會取代先前的值，而不會建立新的物件版本。

重要

註釋刪除是永久且不可復原的，即使在版本控制的儲存貯體中也是如此。與版本控制的儲存貯體中的物件不同，註釋沒有刪除標記或版本歷史記錄。刪除註釋後，就無法復原。

複製行為和一致性

當您使用 CopyObject API 複製物件時 （對於小於 5 GiB 的物件），Amazon S3 會在單一操作中隨物件複製註釋。

當您使用分段上傳複製物件時 （例如， AWS CLI 當 AWS SDKs對大於約 8 MB 的物件使用 Transfer Manager 時），預設不會複製註釋。若要包含註釋，請在 AWS CLI 或同等 SDK 組態--copy-props all中指定 。使用此選擇加入，軟體開發套件會讀取來源註釋、完成分段上傳，然後將每個註釋寫入目的地。在上傳完成和上次註釋寫入之間，目的地物件存在，沒有其所有註釋。

考量事項

  • 您無法新增註釋做為 PutObject或分段上傳請求的一部分。若要將註釋新增至物件，請在物件上傳PutObjectAnnotation後呼叫 。若要將具有註釋的現有物件複製到新位置，請使用 CopyObject搭配預設註釋指令。

  • 若要大量新增或更新多個物件的註釋，請使用批次操作來叫用 Lambda 函數，以PutObjectAnnotation呼叫每個物件。如需詳細資訊，請參閱叫用 AWS Lambda 函數。

  • 下列功能不支援註釋：S3 庫存報告、API Gateway、S3 Storage Lens、Amazon S3 File Gateway、Amazon FSx、S3 on Outposts、S3 Express One Zone （目錄儲存貯體） 和 Amazon S3 Files。

  • 為了確保您正在將註釋寫入物件的目前版本，而不是已覆寫的物件，請使用 x-amz-object-if-match 條件式標頭搭配 PutObjectAnnotation或 DeleteObjectAnnotation。此標頭會驗證父物件的 ETag，以確認自呼叫者上次讀取物件以來，物件未被覆寫。新增標籤或註釋不會變更 ETag。

  • 您無法根據存在或不存在其他註釋的條件新增註釋。x-amz-object-if-match 標頭只會驗證父物件的 ETag，而非註釋狀態。

  • 註釋承載必須是有效的 UTF-8 編碼文字。若要存放二進位資料，請先使用 Base64 編碼資料，再寫入註釋。

  • 您可以對任何儲存類別中的物件呼叫註釋 API GetObjectAnnotation操作 (PutObjectAnnotation、ListObjectAnnotations、、DeleteObjectAnnotation)，包括 S3 Glacier 和 S3 Glacier Deep Archive，而無需先還原物件。

其他組態

本節說明註釋與其他組態的關聯。

複寫

如果您在儲存貯體上設定了 S3 複寫，Amazon S3 會自動複寫註釋。每個註釋都會獨立複寫。如需詳細資訊，請參閱Amazon S3 複寫的內容？。

若要複寫註釋，請將 s3:GetObjectVersionAnnotationForReplication新增至複寫 IAM 角色中的來源儲存貯體許可。如需詳細資訊，請參閱設定即時複寫的許可。

若要在允許物件複寫時防止註釋複寫，請在複寫角色政策s3:ReplicateObjectAnnotation中新增 的拒絕陳述式。物件複寫會繼續成功；只會封鎖註釋複寫。

事件通知

建立、更新或刪除註釋時，Amazon S3 可以傳送事件通知。您可以設定下列事件類型：

  • s3:ObjectAnnotation:Put – 在建立或更新註釋時傳送。

  • s3:ObjectAnnotation:Delete – 刪除註釋時傳送。

如需詳細資訊，請參閱事件通知類型與目的地。