# 使用对象元数据
Amazon S3 中有两种对象元数据：*系统定义的元数据* 和*用户定义的元数据*。系统定义的元数据包括对象的创建日期、大小和存储类等元数据。用户定义的元数据是您可以在上传对象时选择设置的元数据。用户定义的元数据是一组名称/值对。有关更多信息，请参阅[系统定义的对象元数据](#SysMetadata)和[用户定义的对象元数据](#UserMetadata)。
创建对象时，请指定*对象键*（或*键名称*），它在 Amazon S3 存储桶中唯一地标识该对象。有关更多信息，请参阅 [为 Amazon S3 对象命名](object-keys.md)。也可以在上传对象时在 Amazon S3 中设置[用户定义的元数据](#UserMetadata)。
上传对象后，您将无法修改此用户定义的元数据。修改此元数据的唯一方式是创建对象的副本并设置元数据。有关使用 Amazon S3 控制台编辑元数据的更多信息，请参阅[在 Amazon S3 控制台中编辑对象元数据](add-object-metadata.md)。
**使用 S3 元数据查询元数据并加快数据发现速度**
要轻松查找、存储和查询 S3 对象的元数据，可以使用 S3 元数据。借助 S3 元数据，可以快速准备数据，以用于业务分析、内容检索、人工智能和机器学习（AI/ML）模型训练等。
S3 元数据通过自动捕获通用存储桶中对象的元数据，并将其存储在您可以查询的只读、完全托管式 Apache Iceberg 表中，从而加快数据发现速度。这些只读表称为*元数据表*。在通用存储桶中添加、更新和移除对象时，S3 元数据会自动刷新相应的元数据表，以反映最新的更改。
默认情况下，S3 元数据提供[系统定义的对象元数据](#SysMetadata)，例如对象的创建时间和存储类，以及自定义元数据，例如对象上传期间包含的标签和[用户定义的元数据](#UserMetadata)。S3 元数据还提供事件元数据，例如何时更新或删除对象，以及发出请求的 AWS 账户。
元数据表存储在 S3 表存储桶中，这些表存储桶可提供针对表数据进行优化的存储。要查询您的元数据，您可以将表存储桶与 AWS 分析服务（例如 Amazon Athena、Amazon Redshift 和 Amazon Quick）集成。
有关 S3 元数据的更多信息，请参阅[使用 S3 元数据表发现您的数据](metadata-tables-overview.md)。
## 系统定义的对象元数据
对存储桶中存储的每个对象，Amazon S3 将保留一组系统元数据。Amazon S3 将根据需要处理此系统元数据。例如，Amazon S3 将保留对象创建日期和大小元数据，并将此信息用作对象管理的一部分。
有两种类别的系统元数据：
+ **受系统控制**：元数据（例如对象创建日期）受系统控制，这意味着仅 Amazon S3 可以修改日期值。
+ **受用户控制** – 其他系统元数据（例如，为对象配置的存储类以及对象是否已启用服务器端加密）是您可以控制其值的系统元数据的示例。如果存储桶配置为网站，有时您可能想要将页面请求重定向到其它页面或外部 URL。在这种情况下，网页就是您的存储桶中的对象。Amazon S3 将存储页面重定向值作为您可以控制的系统元数据。
创建对象时，您可以配置这些系统元数据项目的值或在需要时更新这些值。有关存储类的更多信息，请参阅 [了解和管理 Amazon S3 存储类](storage-class-intro.md)。
Amazon S3 使用 AWS KMS 密钥加密您的 Amazon S3 对象。AWS KMS 只加密对象数据。校验和与指定的算法存储为对象元数据的一部分。如果请求为对象进行服务器端加密，则校验和将以加密形式存储。有关服务器端加密的更多信息，请参阅 [利用加密来保护数据](UsingEncryption.md)。
**注意**
`PUT` 请求标头的大小限制为 8KB。在 `PUT` 请求标头中，系统定义的元数据的大小限制为 2KB。通过计算每个键和值的 US-ASCII 编码中的字节总数来测量系统定义的元数据的大小。
下表提供了系统定义的元数据列表以及您是否可以更新它。
| 名称 | 描述 | 用户是否可以修改该值？ |
| --- | --- | --- |
| Date | 当前日期和时间。 | 否 |
| Cache-Control | 用于指定缓存策略的常规标头字段。 | 是 |
| Content-Disposition | 对象演示信息。 | 是 |
| Content-Encoding | 已应用于对象的数据的内容编码（如压缩） | 是 |
| Content-Length | 对象大小（以字节为单位）。 | 否 |
| Content-Type | 对象类型。 | 是 |
| Last-Modified | 对象创建日期或上次修改日期（以较晚者为准）。对于分段上传，对象的创建日期是开始分段上传的日期。 | 否 |
| ETag | 表示对象的特定版本的实体标签（ETag）。对于未作为分段上传上传、未加密或使用 Amazon S3 托管密钥 (SSE-S3) 的服务器端加密进行加密的对象，ETag 是数据的 MD5 摘要。 | 否 |
| x-amz-server-side-encryption | 一个标头，它指示是否为对象启用了服务器端加密，以及加密是使用 AWS Key Management Service（AWS KMS）密钥（SSE-KMS），还是使用 Amazon S3 托管式加密密钥（SSE-S3）。有关更多信息，请参阅 [使用服务器端加密保护数据](serv-side-encryption.md)。 | 是 |
| x-amz-checksum-crc64nvme, x-amz-checksum-crc32, x-amz-checksum-crc32c, x-amz-checksum-sha1, x-amz-checksum-sha256 | 包含对象的校验和或摘要的标头。最多一次设置其中一个标头，具体取决于您指示 Amazon S3 使用的校验和算法。有关选择校验和算法的更多信息，请参阅[在 Amazon S3 中检查对象完整性](checking-object-integrity.md)。 | 否 |
| x-amz-checksum-type | 校验和类型，它决定如何组合分段级校验和来为多分段对象创建对象级校验和。 | 是 |
| x-amz-version-id | 对象版本。对存储桶启用版本控制时，Amazon S3 会为添加到存储桶的对象指定版本 ID。有关更多信息，请参阅 [使用 S3 版本控制保留对象的多个版本](Versioning.md)。 | 否 |
| x-amz-delete-marker | 一个布尔值标记，指示对象是否为删除标记。此标记仅在启用了版本控制的存储桶中使用。 | 否 |
| x-amz-storage-class | 用于存储对象的存储类。有关更多信息，请参阅 [了解和管理 Amazon S3 存储类](storage-class-intro.md)。 | 是 |
| x-amz-website-redirect-location | 一个标头，用于将对于关联对象的请求重定向到同一个存储桶中的其他对象或外部 URL。有关更多信息，请参阅 [（可选）配置网页重定向](how-to-page-redirect.md)。 | 是 |
| x-amz-server-side-encryption-aws-kms-key-id | 一个标头，表示用于加密对象的 AWS KMS 对称加密 KMS 密钥的 ID。此标头仅在 x-amz-server-side-encryption 标头存在且值为 aws:kms 时使用。 | 是 |
| x-amz-server-side-encryption-customer-algorithm | 一个标头，指示是否启用了具有客户提供的加密密钥的服务器端加密（SSE-C）。有关更多信息，请参阅 [使用具有客户提供的密钥的服务器端加密（SSE-C）](ServerSideEncryptionCustomerKeys.md)。 | 是 |
| x-amz-tagging | 对象的标签集。标签集必须编码为 URL 查询参数。 | 是 |
## 用户定义的对象元数据
上传对象时，您也可以将元数据指定给该对象。发送 `PUT` 或 `POST` 请求以创建对象时，您将以名称-值（键-值）对的形式提供此可选信息。如果使用 REST API 上传对象，可选的用户定义的元数据名称必须以 `x-amz-meta-` 开头，以与其他 HTTP 标头区分开来。使用 REST API 检索对象时，将返回此前缀。如果使用 SOAP API 上传对象则无需前缀。使用 SOAP API 检索对象时，无论您使用哪种 API 上传对象，都将删除前缀。
**注意**
Amazon S3 的 SOAP API 不适用于新客户，并将于 2025 年 8 月 31 日接近使用寿命终止（EOL）。我们建议您使用 REST API 或 AWS 软件开发工具包。
通过 REST API 检索元数据时，Amazon S3 会将具有相同名称（不分大小写）的标头合并为逗号分隔的列表。如果某些元数据包含不可打印的字符，则不会返回它。但是，`x-amz-missing-meta` 标头将与不可打印的元数据条目的数量值一起返回。该 `HeadObject` 操作从对象检索元数据而不返回对象本身。如果您只对某个对象的元数据感兴趣，则此操作很有用。要使用 `HEAD`，您必须具有对象的 `READ` 访问权限。有关更多信息，请参阅 * Amazon Simple Storage Service API 参考* 中的 [HeadObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html)。
用户定义的元数据是一组键值对。Amazon S3 以小写形式存储用户定义的元数据键。
Amazon S3 允许元数据值中有任意 Unicode 字符。
为避免与这些元数据值的显示有关的问题，如果使用 SOAP 或通过 `POST` 进行基于浏览器的上传，则当使用 REST 和 UTF-8 时，应遵守使用 US-ASCII 字符的规定。
在元数据值中使用非 US-ASCII 字符时，将检查提供的 Unicode 字符串中是否存在非 US-ASCII 字符。此类标头的值在存储前按照 [RFC 2047](https://datatracker.ietf.org/doc/html/rfc2047) 进行字符解码，并在返回前按照 [RFC 2047](https://datatracker.ietf.org/doc/html/rfc2047) 进行编码以确保邮件安全。如果字符串仅包含 US-ASCII 字符，则按原样显示。
示例如下：
```
PUT /Key HTTP/1.1
Host: amzn-s3-demo-bucket.s3.amazonaws.com
x-amz-meta-nonascii: ÄMÄZÕÑ S3
HEAD /Key HTTP/1.1
Host: amzn-s3-demo-bucket.s3.amazonaws.com
x-amz-meta-nonascii: =?UTF-8?B?w4PChE3Dg8KEWsODwpXDg8KRIFMz?=
PUT /Key HTTP/1.1
Host: amzn-s3-demo-bucket.s3.amazonaws.com
x-amz-meta-ascii: AMAZONS3
HEAD /Key HTTP/1.1
Host: amzn-s3-demo-bucket.s3.amazonaws.com
x-amz-meta-ascii: AMAZONS3
```
**注意**
`PUT` 请求标头的大小限制为 8KB。在 `PUT` 请求标头中，用户定义的元数据的大小限制为 2KB。通过计算每个键和值的 UTF-8 编码中的字节总数来测量用户定义的元数据的大小。
有关在上传对象后通过创建对象的副本、修改对象、替换旧对象或创建新版本来更改对象的元数据的信息，请参阅[在 Amazon S3 控制台中编辑对象元数据](add-object-metadata.md)。