使用对象元数据

元数据概览

对象可以具有关联的元数据,这些元数据控制着 GET 请求处理方式的各个方面,包括 Content-Type、Cache-Control、Content-Disposition 和 Content-Encoding(以下各小节会对这些元数据进行详细介绍)。此外,您还可以设置自定义元数据,以供应用可用来标记特定对象拥有某种属性等。

您可以通过两种方式设置对象的元数据:

  • 您可以在上传时使用 gsutil -h 选项指定一个或多个要与对象关联的元数据属性。例如,以下命令会使 gsutil 为从名为 images 的本地目录上传的每个文件设置 Content-Type 和 Cache-Control:

    gsutil -h "Content-Type:text/html" \
           -h "Cache-Control:public, max-age=3600" cp -r images \
           gs://bucket/images
    

    请注意,-h 是 gsutil 命令的一个选项,而不是 cp 子命令。

  • 您可以使用 gsutil setmeta 命令设置或移除已上传对象的元数据字段。请参阅 gsutil 帮助:setmeta

下面详细介绍了特定的元数据部分。

Content-Type

最常设置的元数据是 Content-Type(也称为 MIME 类型),可让浏览器正确呈现对象。在上传时,gsutil 会根据每个文件扩展名自动设置 Content-Type。 例如,上传名称以 .txt 结尾的文件会将 Content-Type 设置为 text/plain。如果您在 Linux 或 macOS 上运行 gsutil,并且希望根据命名和内容检查设置内容类型,请参阅 .boto 配置文件中的 use_magicfile 配置变量。通常,使用 use_magicfile 是一种更加可靠且可配置的做法,但在 Windows 上不适用。

如果您在上传内容时使用 -h 指定了 Content-Type(如前一部分中提供的示例 gsutil 命令),则它会替换基于文件扩展名或内容设置的 Content-Type。 如果 Content-Type 检测算法无法按预期处理您的某些文件,这种做法将非常实用。

Cache-Control

另一常设置的元数据是 Cache-Control,它可让您控制浏览器和互联网缓存是否可以缓存您的对象以及缓存多长时间。Cache-Control 仅适用于具有 public-read ACL 的对象。非公开数据不可缓存。

以下示例从名为 photos 的本地目录中上传一组允许缓存的对象:

gsutil -h "Cache-Control:public,max-age=3600" cp -a public-read \
       -r photos gs://bucket/photos

此命令将上传 photos 目录(和子目录)中的所有文件,使这些文件可被公开读取和缓存,并将缓存过期时间设置为一小时。

请注意,如果允许缓存,则在下载时,您可能会在上传较新的替代对象之后看到对象的旧版本。另请注意,由于对象可以在互联网上的各个位置缓存,因此无法强制缓存对象在全局范围内过期(与强制浏览器刷新其缓存的方式不同)。如果您想阻止提供可公开读取对象的缓存版本,请在该对象上设置 "Cache-Control:no-cache, max-age=0"。您可以使用类似下面的命令来完成此操作:

gsutil -h "Cache-Control:no-cache,max-age=0" \
       cp -a public-read file.png gs://your-bucket

Cache-Control 的另一个用法是通过“no-transform”值,该值指示 Cloud Storage 根据下载请求的具体情况不应用任何内容转换,例如,为不兼容的客户端移除 gzip 内容编码。请注意,只有 XML API 支持此参数。Cloud Storage JSON API 仅支持 public、private、no-cache 和 max-age Cache-Control 参数。

如需详细了解如何设置 Cache-Control 元数据,请参阅 gsutil 帮助:setmeta

Content-Encoding

您可以指定 Content-Encoding 来指示压缩对象(例如使用 gzip 压缩)并同时保留其 Content-Type。 您将需要确保已使用指定的 Content-Encoding 对文件进行了压缩,然后才能使用 gsutil 上传这些文件。请考虑下面这个 Linux 示例:

echo "Highly compressible text" | gzip > foo.txt
gsutil -h "Content-Encoding:gzip" \
       -h "Content-Type:text/plain" \
       cp foo.txt gs://bucket/compressed

请注意,这与通过 Content-Type: application/x-gzip 上传经过压缩(gzip 格式)的对象 foo.txt.gz 不同,因为大多数浏览器都能够根据底层 Content-Type 动态解压缩和处理使用 Content-Encoding:gzip 传送的对象。

对于可压缩的内容,使用 Content-Encoding: gzip 可以节省网络和存储费用,并提高内容传送性能。但是,对于本身已经压缩的内容(例如归档和许多媒体格式),通过 Content-Encoding 应用另一层压缩通常会不利于对象的大小和性能,因此应避免此操作。

另请注意,gsutil 提供了一种简单方法,使内容能够通过 Content-Encoding: gzip 进行压缩和存储:请参阅 gsutil 帮助:cp 中的 -z 和 -Z 选项。

Content-Disposition

您可以在对象上设置 Content-Disposition,以指定与要传输的数据有关的展示信息。以下示例展示了如何从名为 attachments 的本地目录上传文件:

gsutil -h 'Content-Disposition:attachment; filename=filename.ext' \
       cp -r attachments gs://bucket/attachments

通过设置 Content-Disposition,您可以控制内容的展示样式,例如,确定是应自动显示附件,还是需要用户执行某种形式的操作才能打开它。如需详细了解 Content-Disposition 的含义,请参阅 https://tools.ietf.org/html/rfc6266

自定义元数据

您可以将自己的自定义元数据(例如,供应用使用的元数据)添加到 Cloud Storage 对象中,只需将“x-goog-meta”与 -h 配合使用即可。例如:

gsutil -h x-goog-meta-reviewer:jane cp mycode.java gs://bucket/reviews

您可以为每个对象添加多个不同名称的自定义元数据字段。

可设置的字段;字段值

您无法设置某些元数据字段,例如 ETag 和 Content-Length。您可以设置以下字段:

  • Cache-Control
  • Content-Disposition
  • Content-Encoding
  • Content-Language
  • Content-Type
  • 自定义元数据

字段名称不区分大小写。

所有字段及其值必须仅包含 ASCII 字符,但 x-goog-meta- 字段的值除外,此类值可以包含任意 Unicode 值。请注意,使用 XML API 设置元数据时(该 API 将自定义元数据作为 HTTP 标头发送),系统会先使用 UTF-8 对 Unicode 字符进行编码,然后再采用网址编码转换为 ASCII。例如:

gsutil setmeta -h "x-goog-meta-foo: ã" gs://bucket/object

上述命令会存储“foo”和“%C3%A3”自定义元数据键值对。 之后,如果使用 JSON API 运行“ls -L”来列出对象的元数据,则将输出“%C3%A3”,而如果使用 XML API 运行“ls -L”,则将自动对该值进行网址编码,并输出字符“ã”。

查看当前设置的元数据

您可以使用以下命令查看对象当前设置了哪些元数据:

gsutil ls -L gs://the_bucket/the_object