# 为对象添加注释
<a name="annotations-overview"></a>

使用注释可将命名的数据有效载荷附加到您的 Amazon S3 对象。每个注释都是一个大小介于 1 字节到 1 MiB 之间的自定义元数据有效载荷，您无需修改对象本身即可创建、检索、列出和删除它。

您最多可以将 1000 个注释与一个对象版本关联。每个注释都有唯一的名称，可以存储结构化数据，例如人工智能生成的标签、文档上下文、处理结果或合规性记录。

常见使用案例包括将机器学习推理结果、人工智能生成的嵌入内容、内容审核标签、文档分类输出、数据血统和审计跟踪记录、诸如 PII 标志或保留策略等合规性标签、医学影像元数据、数字资产版权信息以及 ETL 管道状态与源对象一起存储。

您可以使用专用的 API 操作管理注释，因此无需重新上传对象，即可添加或更新元数据。

您可以在 S3 元数据配置中启用注释表，以便使用 Athena 和其它分析服务，对注释数据进行大规模查询。S3 元数据将注释数据存储在完全托管式 Apache Iceberg 表中，Amazon S3 自动使这些数据保持最新。有关更多信息，请参阅 [使用 S3 元数据表发现您的数据](metadata-tables-overview.md)。

可以在所有商业 Amazon 区域和中国区域（北京和宁夏）中使用注释。注释在中东（阿联酋）和中东（巴林）区域中不可用。S3 元数据注释表在所有提供 S3 元数据的区域中均可用。

## 何时使用注释与对象标签
<a name="annotations-vs-tags"></a>

使用以下比较来确定注释或对象标签是否最适合您的使用案例。


| 特征 | 对象标签 | 注释 | 
| --- | --- | --- | 
| 每个对象的最大值 | 每个对象版本 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 操作
<a name="annotations-api-operations"></a>

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`，这表示注释表的当前状态。

## 注释限制
<a name="annotations-limits"></a>

每个对象版本最多支持 1000 个注释。与对象版本关联的注释必须具有唯一的注释名称。以下限制适用：
+ 注释名称的长度可达 512 字节（UTF-8），具体取决于下面的命名规则。
+ 注释有效载荷的大小必须介于 1 字节到 1 MiB 之间。
+ 每个对象的总注释存储空间可能多达 1 GiB（1000 个注释，每个 1 MiB）。
+ 支持的校验和算法：CRC32、CRC32C、CRC64NVME、SHA1、SHA256、SHA512、XXHASH64、XXHASH3、XXHASH128。

## 注释命名规则
<a name="annotations-naming-rules"></a>

注释名称必须满足以下要求：
+ 长度必须在 1 到 512 字节之间。
+ 只能包含以下字符：字母（任何语言）、数字（0-9）、下划线 (`_`)、句点 (`.`) 和连字符 (`-`)。
+ 不能以 `aws` 或 `s3` 开头（不区分大小写）。例如，`aws`、`AWS`、`s3` 和 `S3` 都是保留前缀。
+ 不能为空或仅包含空格。

## 加密
<a name="annotations-encryption"></a>

注释使用与父对象相同的加密配置自动进行静态加密。加密类型继承自父对象，而不是存储桶默认值。
+ **SSE-S3**：如果父对象使用具有 Amazon S3 托管式密钥的服务器端加密（SSE-S3），则注释使用 SSE-S3 进行加密。如果父对象未配置服务器端加密，则注释默认使用 SSE-S3 进行加密。
+ **SSE-KMS**：如果父对象使用具有 Amazon KMS 密钥的服务器端加密（SSE-KMS），则注释使用相同的 KMS 密钥进行加密。这同时适用于客户自主管理型密钥和 Amazon 托管式密钥。支持 S3 存储桶密钥。
+ **DSSE-KMS**：如果父对象使用具有 Amazon KMS 密钥的双层服务器端加密（DSSE-KMS），则注释通过使用相同密钥的 DSSE-KMS 进行加密。
+ **SSE-C**：注释不支持具有客户提供的密钥的服务器端加密（SSE-C）。如果您尝试向使用 SSE-C 加密的对象添加注释，Amazon S3 将返回错误。

## 校验和
<a name="annotations-checksums"></a>

使用 `PutObjectAnnotation` 上传注释时，可以提供校验和来验证数据完整性。注释的校验和算法独立于父对象的校验和算法。

使用 `CopyObject` 复制对象时，Amazon S3 将保留源中的注释校验和值。如果您在复制请求中指定了不同的校验和算法，则新算法将同时应用于对象及其注释。

支持的算法：CRC32、CRC32C、CRC64NVME、SHA1、SHA256、SHA512、XXHASH64、XXHASH3、XXHASH128。

如果注释没有指定的校验和算法或校验和值，Amazon S3 会使用 CRC-64/NVME 算法来计算注释的校验和值。

## 版本控制行为
<a name="annotations-versioning"></a>

注释附加到特定的对象版本。

一个对象版本的注释独立于同一对象的其它版本上的注释。创建新版本不会复制先前版本中的注释。在一个版本上删除或添加注释不会影响其它版本上的注释。覆盖对象会将其注释替换为新版本所具有的任何注释（如果没有，则实际上会删除注释）。

添加、更新或移除注释不会修改父对象的 ETag。

在不受版本控制的存储桶中，如果您删除或覆盖对象，则注释会随之删除。

在受版本控制的存储桶中，以下行为适用：
+ 简单的 DELETE 请求（不指定版本 ID）会创建删除标记，但会保留基础版本上的注释。
+ 删除特定版本 ID 会删除该版本和所有关联的注释。
+ 注释不是独立进行版本控制的。当您覆盖同名的注释时，Amazon S3 会替换之前的值，而不创建新的对象版本。

**重要**  
注释删除是永久性且不可逆的，即使在受版本控制的存储桶中也是如此。与受版本控制的存储桶中的对象不同，注释没有删除标记或版本历史记录。一旦删除注释，就无法恢复。

## 复制行为和一致性
<a name="annotations-copy-behavior"></a>

当您使用 `CopyObject` API 复制对象（对于小于 5 GiB 的对象）时，Amazon S3 会在单个操作中将注释与对象一起复制。

当您使用分段上传来复制对象时（例如，当 Amazon CLI 或 Amazon SDK 使用传输管理器来传输大于约 8 MB 的对象时），默认情况下不会复制注释。要包含注释，请在 Amazon CLI 或等效的 SDK 配置中指定 `--copy-props all`。通过这一选择加入，SDK 读取源注释，完成分段上传，然后将每个注释写入目标。在上传完成与最后一次注释写入之间，目标对象存在，但此时没有其所有注释。

## 注意事项
<a name="annotations-considerations"></a>
+ 您不能在 `PutObject` 过程或分段上传请求中添加注释。要向对象添加注释，请在上传对象后调用 `PutObjectAnnotation`。要将现有对象及其注释复制到新位置，请将 `CopyObject` 与默认注释指令结合使用。
+ 要批量添加或更新多个对象的注释，请使用批量操作来调用对每个对象调用 `PutObjectAnnotation` 的 Lambda 函数。有关更多信息，请参阅 [调用 Amazon Lambda 函数](batch-ops-invoke-lambda.md)。
+ 以下功能不支持注释：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`），而无需先还原对象。

## 其他配置
<a name="annotations-additional-configurations"></a>

本节解释注释如何与其它配置相关。

### 复制
<a name="annotations-replication"></a>

如果您在存储桶上配置了 S3 复制，Amazon S3 将自动复制注释。每个注释都独立复制。有关更多信息，请参阅 [Amazon S3 复制什么内容？](replication-what-is-isnot-replicated.md)。

要复制注释，请在您的复制 IAM 角色中向源存储桶权限添加 `s3:GetObjectVersionAnnotationForReplication`。有关更多信息，请参阅 [为实时复制设置权限](setting-repl-config-perm-overview.md)。

要在支持对象复制的同时防止注释复制，请在复制角色策略中为 `s3:ReplicateObjectAnnotation` 添加拒绝语句。对象复制继续成功；只阻止注释复制。

### 事件通知
<a name="annotations-event-notifications"></a>

Amazon S3 可以在创建、更新或删除注释时发送事件通知。您可以配置以下事件类型：
+ `s3:ObjectAnnotation:Put`：创建或更新注释时发送。
+ `s3:ObjectAnnotation:Delete`：删除注释时发送。

有关更多信息，请参阅 [事件通知类型和目标](notification-how-to-event-types-and-destinations.md)。