Cloud Storage 对象简介

本页面介绍了对象（Cloud Storage 中的一种资源）。如需大致了解 Cloud Storage 的工作原理，请参阅 Cloud Storage 产品概览。

对象

对象是您存储在 Cloud Storage 中的各个数据。 您可以在存储桶中创建的对象数量不受限制。

对象包含两个组成部分：对象数据和对象元数据。对象数据通常是您希望在 Cloud Storage 中存储的文件，对 Cloud Storage 完全不透明。对象元数据是描述各种对象特质的“名称-值”对的集合。

所有对象通用的两个重要对象元数据是对象的名称及其世代编号。向 Cloud Storage 存储桶添加对象时，您需要指定对象名称，而 Cloud Storage 会分配世代编号。名称和世代一起唯一标识该存储桶中的对象。

您可以使用访问控制列表 (ACL) 来控制对各个对象的访问权限。您还可以使用 Identity and Access Management (IAM) 来控制对存储桶或托管文件夹中所有对象的访问权限。

命名注意事项

您为对象指定的名称必须符合以下要求：

  • 对象名称可以包含任何有效 Unicode 字符序列（采用 UTF-8 编码时，长度为 1-1024 字节）。
  • 对象名称不能包含回车符或换行符。
  • 对象名称不能以 .well-known/acme-challenge/ 开头。
  • 对象不可命名为 . 或 ..。

强烈建议您不要在对象名称中包含以下内容：

  • XML 1.0 中非法的控制字符（#x7F–#x84 和 #x86–#x9F）：当您尝试列出对象时，这些字符将导致 XML 列出功能出现问题。
  • # 字符：Google Cloud CLI 命令会将以 #<numeric string> 结尾的对象名称解释为版本标识符，因此，如果对象名称中包含 #，您将很难或无法使用 gcloud CLI 对此类版本控制的对象执行操作。
  • [、]、* 或 ? 字符：Google Cloud CLI 命令会将这些字符解释为通配符，因此，如果对象名称中包含它们，您将很难或将无法执行通配符操作。此外，* 和 ? 在 Windows 中是无效的文件名字符。
  • :、"、<、> 或 | 字符：这些是 Windows 中无效的文件名字符，因此尝试将在对象名称中使用此类字符的对象下载到 Windows 文件会失败，除非下载方法包括重命名生成的 Windows 文件。虽然 / 字符在 Windows 中也是无效的文件名字符，但通常可以在对象名称中使用它来模仿目录结构；在下载到 Windows 环境时，Google Cloud CLI 等工具会自动将该字符转换为 \。
  • 敏感信息或个人身份信息 (PII)：对象名称的显示范围比对象数据更广泛。例如，对象名称会显示在对象的网址中，并且在列出存储桶中的对象时也会显示。

您无法直接重命名现有对象，但可以通过复制和删除原始对象来间接重命名对象。

对象命名空间

对象名称保存在存储桶内的平面命名空间中。这意味着：

  • 不同的存储桶可以包含名称相同的对象。
  • 对象不在存储桶的子目录中。

为方便起见，您可以通过多种方式将对象视为存储在文件夹层次结构中：

例如，如果您在存储桶 your-bucket 中创建名为 folder1/file.txt 的对象，则该对象的路径为 your-bucket/folder1/file.txt，且 Cloud Storage 未在其中存储名为 folder1 的文件夹。从 Cloud Storage 的角度来看，字符串 folder1/ 是该对象的名称的一部分。

但是，由于该对象的名称中包含 /，因此某些工具会实现文件夹的外观。例如，使用 Google Cloud 控制台时，您可以找到对象 folder1/file1.txt，就像它是名为 folder1 文件夹中名为 file1.txt 的一个对象。同样，您可以创建名为 folder1 的托管文件夹，然后 file1.txt 将受到此托管文件夹设置的访问权限政策的约束。

请注意，由于对象位于平面命名空间中，因此在列出深度嵌套的子目录时，深度嵌套的目录式结构的性能不如原生文件系统。

请参阅请求率最佳实践，了解如何通过避免在大规模上传期间使用顺序名称来优化性能。使用顺序名称上传的对象可能会到达同一后端服务器并限制性能。

模拟的文件夹

为了帮助您整理 Cloud Storage 存储桶中的对象，一些工具会模拟文件夹，并且 JSON API 和 XML API 都具有可让您设计自己的命名方案来模拟文件夹的功能。请点击以下标签页，了解不同工具如何处理模拟的文件夹。

控制台

Google Cloud 控制台会以类似于本地文件浏览器的文件夹创建可视化的表示形式。

在 Google Cloud 控制台中，您可以在存储桶中创建一个空文件夹，也可以上传现有文件夹。

当您上传现有文件夹时，该文件夹的名称将成为文件夹中所有对象的路径的一部分。所有子文件夹及其包含的对象也会包含在上传内容中。

要创建文件夹，请执行以下操作：

  1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。

    进入“存储桶”

  2. 导航到存储桶。

  3. 点击创建文件夹以创建一个新的空文件夹，或点击上传文件夹以上传现有文件夹。

命令行

Cloud Storage CLI 使用各种规则模拟典型的命令行目录体验。

为了实现分层文件树的视觉效果，gcloud CLI 会应用以下规则来确定应将命令中的目标网址视为对象名称还是文件夹：

  1. 如果目标网址以 / 字符结尾，则 gcloud CLI 命令会将目标网址视为文件夹。例如，假设存在以下命令，其中 your-file 是文件的名称：

    gcloud storage cp your-file gs://your-bucket/abc/

    完成此命令后，Cloud Storage 会在存储桶 your-bucket 中创建一个名为 abc/your-file 的对象。

  2. 如果您通过使用 --recursive 标志或通配符（例如 **）将多个源文件复制到目标网址，gcloud CLI 会将目标网址视为文件夹。例如，假设存在以下命令，其中 top-dir 是包含 file1 和 file2 等文件的文件夹：

    gcloud storage cp top-dir gs://your-bucket/abc --recursive

    完成此命令后，Cloud Storage 会在存储桶 your-bucket 中创建对象 abc/top-dir/file1 和 abc/top-dir/file2。

  3. 如果这些规则都不适用，则 gcloud CLI 会检查存储桶中的对象来确定目标网址是对象名称还是文件夹。例如，假设存在以下命令，其中 your-file 是文件的名称：

    gcloud storage cp your-file gs://your-bucket/abc

    CLI 会使用 / 分隔符和前缀=abc 针对 your-bucket 发出对象列出请求，以确定 your-bucket 中是否有路径以 abc/ 开头的对象。如果有，gcloud CLI 会将 abc/ 视为文件夹名称，并且该命令会在存储桶 your-bucket 中创建对象 abc/your-file。否则，gcloud CLI 会在 your-bucket 中创建对象 abc。

这种基于规则的方法与许多工具的工作方式不同，后者会创建 0 字节对象来标记文件夹的存在。gcloud CLI 可以理解此类工具采用的多种惯例（例如，将 _$folder$ 添加到 0 字节对象名称末尾的惯例），但不要求此类标记对象实现与 UNIX 命令一致的命名行为。

除了这些规则之外，gcloud CLI 如何处理源文件取决于您是否使用 --recursive 标志。如果您使用该标志，gcloud CLI 会构造对象名称以镜像源目录结构，从递归处理时开始。例如，假设存在以下命令，其中 home/top-dir 是包含 file1 和 sub-dir/file2 等文件的文件夹：

gcloud storage cp home/top-dir gs://your-bucket --recursive

完成此命令后，Cloud Storage 会在存储桶 your-bucket 中创建对象 top-dir/file1 和 top-dir/sub-dir/file2。

相比之下，如果不使用 --recursive 标志进行复制，即使由于存在 ** 等通配符而复制了多个文件，也会生成以源文件的最终路径组成部分命名的对象。例如，再次假设 home/top-dir 是一个包含 file1 和 sub-dir/file2 等文件的文件夹，则命令如下：

gcloud storage cp home/top-dir/** gs://your-bucket

在存储桶 your-bucket 中创建一个名为 file1 的对象和一个名为 file2 的对象。

重试和命名

当 gcloud CLI 重试中断的请求时，您可能会遇到以下问题：第一次尝试会复制部分文件，而后续尝试会遇到已存在的目标文件夹，这会导致对象命名不正确。

例如，假设存在以下命令，其中 your-dir/ 下存在子文件夹（如 dir1 和 dir2），这两个子文件夹都包含文件 abc：

gcloud storage cp ./your-dir gs://your-bucket/new --recursive

如果路径 gs://your-bucket/new 尚不存在，则在第一次成功尝试时，gcloud CLI 会创建以下对象：

new/dir1/abc
new/dir2/abc

但是，在下次成功尝试同一命令时，gcloud CLI 会创建以下对象：

new/your-dir/dir1/abc
new/your-dir/dir2/abc

如需让 gcloud CLI 在每次尝试时都以一致的方式运行，请尝试以下操作：

  1. 在目标网址的末尾添加斜杠，以便 gcloud CLI 始终将其视为文件夹。

  2. 使用gcloud storage rsync。由于 rsync 不使用 Unix cp 定义的文件夹命名规则，因此无论目标子文件夹是否存在，它都会以一致的方式运行。

补充说明

  • 您无法使用 gcloud CLI 创建零字节对象来模拟空文件夹。

  • 将文件下载到本地文件系统时，gcloud CLI 会跳过名称以 / 字符结尾的对象，因为 Linux 和 macOS 不允许创建以 / 结尾的文件。

  • 如果您使用脚本通过组合子路径来构建文件路径，请注意，由于 / 只是位于对象名称中的字符，因此 CLI 将 gs://your-bucket/folder/ 解释为与 gs://your-bucket//folder 不同的对象。

REST API

JSON API

JSON API 中不存在文件夹。您可以使用 prefix 和 delimiter 查询参数缩小列出的对象并模拟文件夹。

例如，如需列出存储桶 my-bucket 中前缀为 folder/subfolder/ 的所有对象，请使用以下网址发出对象列出请求：

"https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=folder/subfolder/"

XML API

XML API 中不存在文件夹，您可以使用 prefix 和 delimiter 查询参数缩小列出的对象并模拟文件夹。

例如，如需列出存储桶 my-bucket 中前缀为 folder/subfolder/ 的所有对象，请使用以下网址发出对象列出请求：

"https://storage.googleapis.com/my-bucket?prefix=folder/subfolder/"

移除模拟文件夹

由于模拟的文件夹实际上并不存在，因此您通常可以通过重命名对象来移除模拟的文件夹，使模拟的文件夹不再存在于对象名称中。例如，如果您有一个名为 folder1/file 的对象，则可以通过将该对象重命名为 file 来移除模拟的文件夹 folder1/。

但是，如果您使用了将零字节对象创建为文件夹占位符的工具（例如 Google Cloud 控制台），则必须删除零字节对象以移除文件夹。

对象不变性

对象是不可变的，这意味着，上传的对象不会在整个存储生命周期内发生改变。对象的存储生命周期指的是从成功创建（如上传）对象到成功删除对象所经历的时间。实际上，这意味着您无法对对象进行增量更改，例如执行附加操作或截断操作。但是，您可以替换存储在 Cloud Storage 中的对象，并且此操作将以原子方式进行：在上传完新版本之前，系统会继续将对象的旧版本传送给读取者，而在上传完成之后，系统则会将对象的新版本传送给读取者。单次替换操作会标记一个不可变对象的生命周期结束以及一个新的不可变对象的生命周期开始。

每次替换对象的数据时，对象的世代编号都会发生更改。因此，世代编号可以唯一地标识不可变对象。

请注意，系统使用每秒一次限制来快速替换同一对象。更频繁地替换同一对象可能会导致 429 Too Many Requests 错误。您应该将应用设计为每秒最多上传一次特定对象的数据，并使用指数退避算法重试策略来处理偶尔出现的 429 Too Many Requests 错误。

后续步骤