用于运行 gcloud storage 的 shim

概览

Cloud SDK 现提供一个新的 CLI（即 gcloud storage），该 CLI 在执行上传和下载操作时比 gsutil 的速度要快得多，并且所需进行的参数调整也更少。这一新的 CLI 具有与 gsutil 类似的语法和命令结构，但在许多重要方面则与 gsutil 完全不同。为了轻松过渡到该新的 CLI，gsutil 提供了一个 shim：如果存在等效命令，它会将 gsutil 命令转换为等效的 gcloud storage 命令；但如果不存在等效命令，则会回退到执行正常的 gsutil 操作。

如何启用

在 [GSUtil] 部分下的 .boto 配置文件中设置 use_gcloud_storage=True：

[GSUtil]
use_gcloud_storage=True

您还可以使用顶级 -o 标志为个别命令设置该标志。

gsutil -o "GSUtil:use_gcloud_storage=True" -m cp -p file gs://bucket/obj

可用命令

gcloud storage CLI 仅支持一部分 gsutil 命令。下面列出了 shim 支持的命令并注明了行为差异。

acl

  • 不支持 ch 子命令。

autoclass

  • 按预期方式执行。

bucketpolicyonly

  • 按预期方式执行。

cat

  • 输出第二个对象的数据，即使第一个对象无效也会如此。

compose

  • 按预期方式执行。

cors

  • get 子命令会输出“[]”，而不是“gs://[bucket name] has no CORS configuration”（gs://[存储桶名称] 没有 CORS 配置）。

cp

  • 复制第二个对象，即使第一个对象无效也会如此。

  • 不支持文件间复制。

  • 支持在云端之间复制对象，只需在名称中添加尾随斜杠即可。

  • 所有版本标志 (-A) 会以静默方式按顺序执行，而不是引发错误。

defacl

  • 不支持 ch 子命令。

defstorageclass

  • 按预期方式执行。

hash

  • 在 gsutil 中，系统会忽略云对象的 -m 和 -c 标志，这些标志会影响显示的哈希值。对于 shim 和 gcloud storage，此行为是固定的。

iam

  • 不支持 ch 子命令。

  • -f 标志将在出现任何错误（不仅仅是 API 错误）时继续存在。

kms

  • authorize 子命令会以不同的格式返回信息类消息。

  • encryption 子命令会以不同的格式返回信息类消息。

标签

  • get 子命令会输出“[]”，而不是“gs://[bucket name] has no labels configuration”（gs://[存储桶名称] 没有标签配置）。

生命周期

  • 按预期方式执行。

日志记录

  • get 子命令具有不同的 JSON 空格设置，并且如果找不到配置，便不会输出信息类消息。

ls

  • 按预期方式执行。

mb

  • 按预期方式执行。

mv

  • 请参阅有关 cp 的说明。

通知

  • list 子命令会将配置信息输出为 YAML。

  • delete 子命令会提供进度跟踪和并行化功能。

pap

  • 按预期方式执行。

rb

  • 按预期方式执行。

requesterpays

  • 按预期方式执行。

rewrite

  • 如果在不使用新键的情况下调用 -k 标志，不会抛出错误。无论是否使用 shim，旧密钥都会被保留。

rm

  • 不支持 $folder$ 删除标记。

rpo

  • 按预期方式执行。

setmeta

  • 如果未更改标头，不会抛出错误。

stat

  • 包含一个“存储类别更新时间：”字段，可能会发生跳格。

ubla

  • 按预期方式执行。

版本控制

  • 按预期方式执行。

web

  • get 子命令具有不同的 JSON 空格设置，并且如果找不到配置，便不会输出信息类消息。

boto 配置

boto 文件中的配置会一对一映射到 gcloud 环境变量（如适用）。

[Credentials]

  • aws_access_key_id: AWS_ACCESS_KEY_ID

  • aws_secret_access_key: AWS_SECRET_ACCESS_KEY

  • use_client_certificate: CLOUDSDK_CONTEXT_AWARE_USE_CLIENT_CERTIFICATE

[Boto]

  • proxy: CLOUDSDK_PROXY_ADDRESS

  • proxy_type: CLOUDSDK_PROXY_TYPE

  • proxy_port: CLOUDSDK_PROXY_PORT

  • proxy_user: CLOUDSDK_PROXY_USERNAME

  • proxy_pass: CLOUDSDK_PROXY_PASSWORD

  • proxy_rdns: CLOUDSDK_PROXY_RDNS

  • http_socket_timeout: CLOUDSDK_CORE_HTTP_TIMEOUT

  • ca_certificates_file: CLOUDSDK_CORE_CUSTOM_CA_CERTS_FILE

  • max_retry_delay: CLOUDSDK_STORAGE_BASE_RETRY_DELAY

  • num_retries: CLOUDSDK_STORAGE_MAX_RETRIES

[GSUtil]

  • check_hashes: CLOUDSDK_STORAGE_CHECK_HASHES

  • default_project_id：CLOUDSDK_CORE_PROJECT

  • disable_analytics_prompt: CLOUDSDK_CORE_DISABLE_USAGE_REPORTING

  • use_magicfile: CLOUDSDK_STORAGE_USE_MAGICFILE

  • parallel_composite_upload_threshold: CLOUDSDK_STORAGE_PARALLEL_COMPOSITE_UPLOAD_THRESHOLD

  • resumable_threshold: CLOUDSDK_STORAGE_RESUMABLE_THRESHOLD

[OAuth2]

  • client_id: CLOUDSDK_AUTH_CLIENT_ID

  • client_secret: CLOUDSDK_AUTH_CLIENT_SECRET

  • provider_authorization_uri: CLOUDSDK_AUTH_AUTH_HOST

  • provider_token_uri: CLOUDSDK_AUTH_TOKEN_HOST

常规兼容性说明

  • 由于在所有主要平台上都兼容，因此默认情况下会为所有命令启用多进程（就像 -m 选项始终包含在 gsutil 中一样）。

  • 超过 2 个星号的序列（如 ***）始终被视为单个星号。

  • 与 gsutil 不同，gcloud 并非用来执行并行调用，并且如果这样做（即同时从两个终端运行 shim）可能会导致不可预测的行为。

  • 假定某存储桶包含一个 gs://bucket/nested/foo.txt 对象，则如果给定类似 gs://bucket/*/nested/* 这样的网址，gsutil 的通配符迭代器会匹配该 foo.txt。而如果给定相同的网址，shim 不会匹配该 foo.txt。

  • 后续会提供更新，因为 gcloud storage 和 shim 均支持新命令。

  • 如果 Unicode 遇到问题，请尝试将环境变量 PYTHONUTF8 设置为 1。具体而言，这可能有助于 Windows 命令行 (CMD)。