从 gsutil 过渡到 gcloud storage

gcloud storage（正式版）是建议用于与 Cloud Storage 交互的命令行工具。本页面通过介绍两种工具之间的主要差异和命令映射，来帮助您从 gsutil 过渡到 gcloud storage。如需详细了解 gcloud storage 工具，请参阅 gcloud storage 参考文档。

如需了解如何安装并开始使用 Google Cloud CLI，请参阅安装 Google Cloud CLI。

行为差异

以下部分介绍了 gsutil 和 gcloud storage 之间的行为差异。

并行调用

gcloud storage 不支持同时从不同终端运行 CLI 的多个实例。

并行处理

gcloud storage 支持并行处理。

通配符处理

gcloud storage 会简化多个星号。如果您连续使用三个或更多星号 (***)，该工具会将它们视为一个星号 (*)。

分层命名空间存储桶的处理

gcloud storage 可用于创建和管理启用了分层命名空间的存储桶。

输出格式

gcloud storage 和 gsutil 命令的输出格式不同。虽然日志记录格式等细微更改可能不会对您造成影响，但错误消息和数据列表中的更显著差异可能会破坏自动化脚本。

如果您具有依赖于解析 gsutil 命令输出的脚本，则应在转换这些脚本之前，先查看并更新它们以适应 gcloud storage 格式。

等效的 gcloud 命令

除了少数几个例外，所有现有的 gsutil 命令在 gcloud storage 中都有等效的命令。您可以访问参考文档或运行 gcloud storage --help 以获得完整的 gcloud storage 命令列表。下表简要概述了常用 gsutil 命令的变化。

操作 gsutil 命令 gcloud storage 命令
管理访问控制列表 (ACL) 
gsutil acl get
gsutil acl set
gsutil acl ch

gcloud storage RESOURCE describe --format="multi(acl:format=json)"
gcloud storage RESOURCE update --acl-file=ACL_FILE_PATH
gcloud storage RESOURCE update --add-acl-grant=GRANT
gcloud storage RESOURCE update --remove-acl-grant=GRANT
操作 gsutil 命令 gcloud storage 命令
串联对象并显示对象内容 
gsutil cat
 
gcloud storage cat
操作 gsutil 命令 gcloud storage 命令
通过将对象合并为新对象来串联对象 
gsutil compose
 
gcloud storage objects compose
备注
如需在 gcloud storage objects compose 中应用前提条件，请使用特定标志，例如 --if-generation-match 或 --if-metageneration-match。
操作 gsutil 命令 gcloud storage 命令
复制对象和其他资源 
gsutil cp
 
gcloud storage cp
备注

使用 Google Cloud 控制台创建的模拟文件夹会被识别为 0 字节占位符对象。gcloud storage cp 可用于复制模拟文件夹，而 gsutil cp 则不能。

在处理错误时，gcloud storage cp 会尝试复制所有资源，即使其中一个资源无效或不存在也是如此。gsutil cp 可能会在遇到无效资源时立即停止整个操作。

下载对象时，gcloud storage cp 会创建目标路径中指定的任何缺失的本地目录。如果目标目录不存在，则 gsutil cp 会失败。
操作 gsutil 命令 gcloud storage 命令
显示对象使用的总磁盘空间 
gsutil du
 
gcloud storage du
操作 gsutil 命令 gcloud storage 命令
计算文件哈希 
gsutil hash
 
gcloud storage hash
备注

gsutil hash 使用加法标志来包含特定哈希，例如 -c 或 -m。gcloud storage hash 使用减法标志来排除哈希，例如 --skip-md5 或 --skip-crc32c。
操作 gsutil 命令 gcloud storage 命令
管理存储桶标签 
gsutil label get
gsutil label set
gsutil label ch

gcloud storage buckets describe
gcloud storage buckets update
gcloud storage buckets update
备注

在单个 gsutil label ch 命令中添加、更新和移除标签的组合行为方式可能与使用 gcloud storage buckets update 的等效操作不同。如果脚本依赖于 gsutil 的特定“读取-修改-写入”行为，则在过渡到 gcloud storage 后，应仔细测试这些脚本。
操作 gsutil 命令 gcloud storage 命令
列出存储桶、对象和文件夹 
gsutil ls
 
gcloud storage ls
备注

使用通配符列出项目中的对象时，gsutil ls 会返回对象的扁平列表，而 gcloud storage ls 会返回按存储桶名称分组的对象。

使用 gcloud storage ls -L 返回详细列表作为输出时，以下行为适用：

  • 每条元数据（也称为“键”）的标签中每个单词的首字母都大写。
  • 如果对象的某条元数据没有值，gcloud storage 会从输出中省略该行。

gcloud storage 始终以世界协调时间 (UTC) 输出日期时间。

gcloud storage 会在命令输出的末尾返回所有错误消息。
操作 gsutil 命令 gcloud storage 命令
移动和重命名对象或目录 
gsutil mv
 
gcloud storage mv
操作 gsutil 命令 gcloud storage 命令
就地重写对象 
gsutil rewrite
 
gcloud storage objects update
备注

如果您的 boto 配置文件中设置了 encryption_key，gsutil rewrite -k 会将该密钥应用于对象。如果未设置 encryption_key，则 gsutil rewrite -k 的等效命令为 gcloud storage objects update --clear-encryption-key。这会从对象中移除所有客户提供的加密密钥 (CSEK) 或客户管理的加密密钥 (CMEK)。然后，使用相应存储桶的默认 KMS 密钥或 Google管理的加密来加密对象。

gsutil rewrite 包含的逻辑会在所请求的转换不会更改对象的状态时（例如，如果对象已处于目标存储类别中），跳过重写对象。gcloud storage objects update 可能不会执行相同的检查，从而可能导致不必要的操作。
操作 gsutil 命令 gcloud storage 命令
移除对象或存储桶 
gsutil rm
 
gcloud storage rm
备注

不支持 gsutil 别名 del、delete 和 remove。

存在一个已知问题，即当 -l 和 -r 标志一起使用时，gsutil 和 gcloud storage 的行为方式会有所不同。在从使用 gsutil 过渡到使用 gcloud storage 之前，应先对通过管道传输要递归删除的目录列表的脚本进行全面测试。
操作 gsutil 命令 gcloud storage 命令
同步两个存储桶或目录的内容 
gsutil rsync
 
gcloud storage rsync
备注

默认情况下，如果对象的大小和上次修改时间在来源和目标之间一致，gsutil rsync 会认为该对象未发生更改。只有在对象缺少修改时间或您使用 -c 标志手动强制执行时，它才会执行更彻底的校验和比较。gcloud storage rsync 也会先检查文件的大小和上次修改时间；不过，如果对象大小一致，但修改时间不同或缺失，它会自动执行校验和比较。

gcloud storage rsync 在默认情况下会并行执行操作，以提高性能。gsutil rsync 会按顺序运行，除非使用顶级 -m 标志。

gsutil rsync 在默认情况下会遵循符号链接。gcloud storage rsync 在默认情况下会忽略这些链接，除非使用 --no-ignore-symlinks 标志。
操作 gsutil 命令 gcloud storage 命令
为上传的对象设置元数据 
gsutil setmeta
 
gcloud storage objects update
备注

gsutil setmeta 使用单个可重复的 -h 标志来指定要设置或移除的元数据。gcloud storage objects update 为每个元数据字段使用不同的标志（例如：--content-type、--clear-cache-control 或 --update-custom-metadata）。

在 gsutil setmeta 中，-h 标志用于设置完整标头名称（例如：-h "x-goog-meta-icecreamflavor:vanilla"）。在 gcloud storage objects update 中，则改为使用 --update-custom-metadata 标志，该标志接受键值对（例如：--update-custom-metadata=icecreamflavor=vanilla）。如需移除自定义元数据字段，gsutil setmeta 使用 -h "x-goog-meta-icecreamflavor"，而 gcloud storage objects update 使用 --remove-custom-metadata=icecreamflavor。
操作 gsutil 命令 gcloud storage 命令
显示对象状态 
gsutil stat
 
gcloud storage objects list --stat --fetch-encrypted-object-hashes
备注

gcloud storage objects list --stat 的输出格式与 gsutil stat 的输出格式不同，存在与间距不一致相关的已知问题。为解析 gsutil stat 的输出而编写的脚本可能需要进行调整，才能处理新的输出格式。

后续步骤

如需详细了解命令和标志映射，请参阅 gsutil GitHub 仓库中的迁移参考。