为对象添加注释
使用注释可将命名的数据有效载荷附加到您的 Amazon S3 对象。每个注释都是一个大小介于 1 字节到 1 MiB 之间的自定义元数据有效载荷，您无需修改对象本身即可创建、检索、列出和删除它。
您最多可以将 1000 个注释与一个对象版本关联。每个注释都有唯一的名称，可以存储结构化数据，例如人工智能生成的标签、文档上下文、处理结果或合规性记录。
常见使用案例包括将机器学习推理结果、人工智能生成的嵌入内容、内容审核标签、文档分类输出、数据血统和审计跟踪记录、诸如 PII 标志或保留策略等合规性标签、医学影像元数据、数字资产版权信息以及 ETL 管道状态与源对象一起存储。
您可以使用专用的 API 操作管理注释，因此无需重新上传对象，即可添加或更新元数据。
您可以在 S3 元数据配置中启用注释表，以便使用 Athena 和其它分析服务，对注释数据进行大规模查询。S3 元数据将注释数据存储在完全托管式 Apache Iceberg 表中，Amazon S3 自动使这些数据保持最新。有关更多信息，请参阅 使用 S3 元数据表发现您的数据。
可以在所有商业 AWS 区域和中国区域（北京和宁夏）中使用注释。注释在中东（阿联酋）和中东（巴林）区域中不可用。S3 元数据注释表在所有提供 S3 元数据的区域中均可用。
何时使用注释与对象标签
使用以下比较来确定注释或对象标签是否最适合您的使用案例。
| 特征 | 对象标签 | 注释 |
|---|---|---|
| 每个对象的最大值 | 每个对象版本 10 个 | 每个对象版本 1000 个 |
| 最大大小 | 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，这表示注释表的当前状态。
注释限制
每个对象版本最多支持 1000 个注释。与对象版本关联的注释必须具有唯一的注释名称。以下限制适用：
-
注释名称的长度可达 512 字节（UTF-8），具体取决于下面的命名规则。
-
注释有效载荷的大小必须介于 1 字节到 1 MiB 之间。
-
每个对象的总注释存储空间可能多达 1 GiB（1000 个注释，每个 1 MiB）。
-
支持的校验和算法：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 算法来计算注释的校验和值。
版本控制行为
注释附加到特定的对象版本。
一个对象版本的注释独立于同一对象的其它版本上的注释。创建新版本不会复制先前版本中的注释。在一个版本上删除或添加注释不会影响其它版本上的注释。覆盖对象会将其注释替换为新版本所具有的任何注释（如果没有，则实际上会删除注释）。
添加、更新或移除注释不会修改父对象的 ETag。
在不受版本控制的存储桶中，如果您删除或覆盖对象，则注释会随之删除。
在受版本控制的存储桶中，以下行为适用：
-
简单的 DELETE 请求（不指定版本 ID）会创建删除标记，但会保留基础版本上的注释。
-
删除特定版本 ID 会删除该版本和所有关联的注释。
-
注释不是独立进行版本控制的。当您覆盖同名的注释时，Amazon S3 会替换之前的值，而不创建新的对象版本。
重要
注释删除是永久性且不可逆的，即使在受版本控制的存储桶中也是如此。与受版本控制的存储桶中的对象不同，注释没有删除标记或版本历史记录。一旦删除注释，就无法恢复。
复制行为和一致性
当您使用 CopyObject API 复制对象（对于小于 5 GiB 的对象）时，Amazon S3 会在单个操作中将注释与对象一起复制。
当您使用分段上传来复制对象时（例如，当 AWS CLI 或 AWS SDK 使用传输管理器来传输大于约 8 MB 的对象时），默认情况下不会复制注释。要包含注释，请在 AWS CLI 或等效的 SDK 配置中指定 --copy-props all。通过这一选择加入，SDK 读取源注释，完成分段上传，然后将每个注释写入目标。在上传完成与最后一次注释写入之间，目标对象存在，但此时没有其所有注释。
注意事项
-
您不能在
PutObject过程或分段上传请求中添加注释。要向对象添加注释，请在上传对象后调用PutObjectAnnotation。要将现有对象及其注释复制到新位置，请将CopyObject与默认注释指令结合使用。 -
要批量添加或更新多个对象的注释，请使用批量操作来调用对每个对象调用
PutObjectAnnotation的 Lambda 函数。有关更多信息，请参阅 调用 AWS Lambda 函数。 -
以下功能不支持注释：S3 清单报告、API Gateway、S3 Storage Lens 存储统计管理工具、Amazon S3 文件网关、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 对数据进行编码。
-
您可以对任何存储类别的对象（包括 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：删除注释时发送。
有关更多信息，请参阅 事件通知类型和目标。
