对象元数据

管理

本页面讨论了 Cloud Storage 中随同对象一起存储的元数据字段。

简介

存储在 Cloud Storag 中的对象具有关联的元数据。 元数据用于标识对象的属性，并指定了访问对象时应如何处理对象。元数据以键值对的形式存在。例如，对象的存储类别由元数据条目 storageClass:STANDARD 表示。storageClass 是元数据的键，所有对象都有这样一个与其关联的键。STANDARD 指定了此特定对象具有的值，该值因对象而异。

元数据的可变性各不相同：有些元数据您随时可以修改，有些元数据您只能在创建对象时设置，有些元数据您只能查看。例如，您可以随时修改 Cache-Control 元数据的值，但只能在创建或重写对象时才能分配 storageClass 元数据，而且不能直接修改 generation 元数据的值；不过，当您替换对象时，generation 值会发生变化。

可修改的元数据

用户可以更改对象的两类元数据：

  • 固定键元数据：设置了键的元数据（但您可以为该元数据指定值）。

  • 自定义元数据：通过指定键以及与该键关联的值而添加的元数据。

修改元数据时，通常应避免使用非 ASCII 字符，因为 XML API 使用的 HTTP 标头中不允许包含这些字符。

固定键元数据

您可以修改对象的以下元数据，但您必须具有足够的权限：

访问权限控制元数据

Cloud Storage 使用 Identity and Access Management (IAM) 和访问控制列表 (ACL) 来控制对象的访问权限。您可以访问这些链接，了解这些访问控制方法和相关元数据。

Cache-Control

Cache-Control 元数据可以指定有关如何从 Cloud Storage 中传送数据的两个不同方面：是否可以缓存数据，以及是否可以转换数据。

缓存数据

利用 Cache-Control 元数据，您可以控制缓存是否可以缓存您的对象以及缓存多长时间，缓存的对象可用于服务未来的请求。缓存可以包括浏览器缓存和互联网缓存，以及 Cloud Storage 内置缓存。

如果适用对象没有 Cache-Control 元数据条目，则 Cloud Storage 会使用以下默认值：

如果您允许缓存，则下载内容可能会继续接收早期版本的对象，即使在上传新版本后也是如此。这是因为在 max-age 确定的时间段内，此类早期版本在缓存中仍被视为处于“全新”状态。此外，由于对象可在互联网上的任何位置缓存，因此无法在全局范围内强制缓存对象到期。这意味着，如果您撤消某个对象的公开访问权限，该对象可能仍可从缓存中提供，具体取决于该对象上次被访问的时间和其 Cache-Control 设置。例如，如果您在 Cache-Control 为 public, max-age=3600 时传送对象，则该对象可在缓存中保留一小时。如果您想阻止传送可公开读取的缓存版对象，请对该对象设置 Cache-Control: no-store。

如果您需要更好地控制缓存行为，可以在存储桶前面配置 Cloud CDN。

转换数据

Cache-Control 元数据还允许您按原样传送存储的对象，而不对数据应用任何转换，例如为不兼容的客户端移除 gzip 内容编码。如需按原样传送对象，请设置 Cache-Control:no-transform。

Content-Disposition

Content-Disposition 元数据指定了与要传输的数据有关的展示信息。通过设置 Content-Disposition，您可以控制内容的展示样式，例如，确定是否应自动显示附件，或者是否需要用户执行某种形式的操作才能打开它。如需了解 Content-Disposition 规范，请参阅 https://datatracker.ietf.org/doc/html/rfc6266。

Content-Encoding

Content-Encoding 元数据可用于指示对象是否已被压缩，同时您仍可保留对象的基本 Content-Type。例如，以 gzip 格式压缩的文本文件可能具有以下特征：Content-Type 表明这是一个文本文件，而 Content-Encoding 表明该文件已采用 gzip 格式进行压缩。您应确保在上传文件之前，确实已使用指定的 Content-Encoding 压缩文件；否则，在尝试下载对象时，可能会发生意外行为。如需了解详情，请参阅“转码”页面。

对于可压缩的内容（例如文本），使用 Content-Encoding: gzip 可节省网络和存储费用，并提高内容传送性能。但是，对于本身已经压缩的内容（例如归档和许多媒体格式），再压缩一次并在 Content-Encoding 元数据中进行标记通常不利于对象的大小和性能，因此应避免此操作。

Content-Language

Content-Language 元数据指示对象面向的语言。如需了解此元数据的典型值，请参阅 ISO 639-1 语言代码。

Cloud Storage 支持的 Content-Language 值长度不超过 100 个字符。

Content-Type

最常设置的元数据是 Content-Type（也称为媒体类型），它使浏览器能够正确呈现对象。所有对象都在自己的 Content-Type 元数据中指定了一个值，但此值不需要与对象的基础类型匹配。例如，如果上传者未指定 Content-Type，也无法确定此属性，则此属性会设置为 application/octet-stream 或 application/x-www-form-urlencoded（具体取决于您上传对象的方式）。 如需查看有效内容类型的列表，请参阅 IANA 媒体类型页面。

Custom-Time

Custom-Time 元数据是用户指定的日期和时间，以 RFC 3339 格式 YYYY-MM-DD'T'HH:MM:SS.SS'Z' 或 YYYY-MM-DD'T'HH:MM:SS'Z'（如果为 0 毫秒）表示。您通常会设置此元数据，以便在对象生命周期管理中使用 DaysSinceCustomTime 条件。

一旦在对象上设置了 Custom-Time，您就无法移除它。此外，Custom-Time 的值不能减少。也就是说，您不能将 Custom-Time 设置为早于现有 Custom-Time 的日期/时间。但是，您可以通过重新编写对象有效地移除或重置 Custom-Time。

对象保全

使用元数据标志放置对象保全，以防止删除或替换对象。如需了解详情，请参阅“对象保全”页面。

保留配置

如果存在对象的保留配置，它会定义一个日期和时间，在该日期和时间之前无法删除或替换该对象。如需了解详情，请参阅对象保留锁定。

自定义元数据

自定义元数据是您为其同时定义键和值的元数据。如需创建自定义元数据，您需要同时指定键和值。创建自定义元数据 key:value 对后，您可以删除键或更改值。

自定义元数据存在大小限制，会产生存储费用。

如需了解如何设置自定义元数据，请参阅“查看和修改元数据”页面。

x-goog-meta- 前缀

XML API 使用请求标头设置和检索对象元数据，JSON API 允许使用请求标头在可续传上传的最终请求中设置自定义元数据。为了将自定义元数据标头与标准请求标头明确区分开来，这两个 API 都会将 x-goog-meta- 作为此类自定义元数据标头的前缀。

不可修改的元数据

您无法直接修改某些元数据。此元数据是在创建或重写对象时设置的。在对象的创建或重写过程中，您可以设置某些此类元数据，例如对象的存储类别或 CMEK（客户管理的加密密钥）。其他元数据会自动添加且仅供查看，例如对象的世代编号或创建时间。

世代编号和元数据世代编号

作为其元数据的一部分，每个 Cloud Storage 对象都有一个数字 generation 属性和一个唯一标识该对象的数字 metageneration 属性：

属性 说明
generation 标识对象的版本，并存在于每个对象中，而无论存储桶是否使用对象版本控制。
  • 对象版本的 generation 值从不改变。同名的新对象可以替换现有对象，但新对象始终分配有不同的 generation。
  • 不能保证连续版本的世代编号会增加，只有每个新版本都有唯一的世代编号。
  • 不相关对象的世代编号之间没有关联（即使这些对象位于同一个存储桶中）。
metageneration 标识元数据版本，每当更新给定 generation 的元数据时都会增加。
  • 对于对象的每个新 generation，metageneration 从 1 开始。
  • 如果没有 generation 属性，则 metageneration 属性毫无意义，因此，后者必须与前者结合在一起使用。比较两个对象版本的元数据世代毫无意义。

generation 和 metageneration 属性适用于以下情况：

校验和

校验和是根据关联对象的数据计算得出的元数据。校验和用于验证对象数据未损坏。Cloud Storage 对象具有多个校验和元数据字段。

CRC32C

所有 Cloud Storage 对象都具有 CRC32C 哈希值。用于计算 CRC32C 的库包括：

Base64 编码的 CRC32C 采用大端序字节顺序。

MD5

Cloud Storage 对象若满足以下条件，则具有 MD5 哈希值：

此哈希值仅适用于完整对象，因此不能对部分下载（因执行范围 GET 请求而导致）执行完整性检查。

ETag

所有 Cloud Storage 对象都具有 ETag。但是，从 XML API 请求时，同一对象可能具有与 JSON API 相比不同的 ETag 值。在大多数情况下，用户不应根据规范做出与在 ETag 中使用的值有关的任何假设（除非它们会随着基础数据或元数据的更改而发生更改）。

如果满足以下所有条件，则对象的 ETag 标头会返回对象的 MD5 值：

修改时间

作为其元数据的一部分，每个 Cloud Storage 对象都有一个 updated 属性，指示对象元数据的上次修改时间。updated 时间最初设置为对象的创建时间，然后只要对象的任何元数据发生变化就会更改。这包括由请求者进行的更改（例如修改自定义元数据），以及 Cloud Storage 代表请求者进行的更改（例如根据对象生命周期配置）。

后续步骤