并行复合上传

上传大型文件的一种策略称为并行复合上传。在此类上传中，一个文件最多会分为 32 个数据块，这些数据块会并行上传到临时对象，系统会使用临时对象重新创建最终对象并删除临时对象。

如果网络和磁盘速度足够快，则并行复合上传的速度明显快于其他方式的上传速度；但是，存储在存储桶中的最终对象是复合对象，它仅包含 crc32c 哈希值，不包含 MD5 哈希值。因此，在使用 Python 应用下载对象时，您必须使用 crcmod 来执行完整性检查。只有在以下情况下，您才应执行并行复合上传：

  • 您不需要上传的对象包含 MD5 哈希值。

  • 任何需要下载对象的 Python 用户（包括 gsutil 用户）都已安装 google-crc32c 或 crcmod。

    例如，如果您使用 Python 上传仅由 Java 应用传送的视频资源，则并行复合上传是一种不错的选择，因为 Java 中提供了高效的 CRC32C 实现。

工具和 API 如何使用并行复合上传

根据您与 Cloud Storage 的交互方式，系统可能会代表您自动管理并行复合上传。本部分介绍不同工具的并行复合上传行为，并说明如何修改该行为。

控制台

Google Cloud 控制台不会执行并行复合上传。

命令行

您可以通过修改以下属性来配置 gcloud storage cp 执行并行复合上传的方式和时间：

  • storage/parallel_composite_upload_enabled：用于启用并行复合上传的属性。如果为 False，则停用并行复合上传。如果为 True 或 None，则对满足其他属性中定义的条件的对象执行并行复合上传。默认设置为 None。

  • storage/parallel_composite_upload_compatibility_check：用于切换安全检查的属性。如果为 True，则 gcloud storage 仅在满足以下所有条件时执行并行复合上传：

    请注意，为了检查这些条件，gcloud CLI 会在上传命令中检索目标存储桶的元数据。

    如果为 False，gcloud storage 不会执行任何检查。默认设置为 True。

  • storage/parallel_composite_upload_threshold：执行并行复合上传的文件总大小下限。默认设置为 150 MiB。

  • storage/parallel_composite_upload_component_size：每个临时对象的大小上限。如果文件总大小太大，以致于按此参数大小分割的数据块数量超过 32 个，则系统会忽略该属性。

  • storage/parallel_composite_upload_component_prefix：为临时对象命名时使用的前缀。此属性可以设置为绝对路径，也可以设置为相对于最终对象的路径。如需了解详情，请参阅属性说明。默认前缀是绝对路径 /gcloud/tmp/parallel_composite_uploads/see_gcloud_storage_cp_help_for_details。

如需修改这些属性，您可以创建命名配置并使用 --configuration 项目范围标志来按命令应用配置，也可以使用 gcloud config set 命令为所有 gcloud CLI 命令应用配置。

使用 gcloud CLI 执行并行复合上传时，系统不需要额外的本地磁盘空间。如果并行复合上传在组合对象之前失败，请再次运行 gcloud CLI 命令，以便对失败的临时对象执行可续传上传。在恢复上传时，系统不会重新上传并行复合上传失败之前已成功上传的任何临时对象。

临时对象的命名方式如下：

TEMPORARY_PREFIX/RANDOM_VALUE_HEX_DIGEST_COMPONENT_ID

其中：

  • TEMPORARY_PREFIX 由 storage/parallel_composite_upload_component_prefix 属性控制。
  • RANDOM_VALUE 是一个随机数值。
  • HEX_DIGEST 是从来源资源名称派生的哈希值。
  • COMPONENT_ID 是组件的序列号。

通常，系统会在并行复合上传结束时删除临时对象，但为了避免遗留临时对象，您应通过 gcloud CLI 命令检查退出状态，并且应手动删除在已取消的任何上传过程中上传的任何临时对象。

客户端库

Java

如需了解详情，请参阅 Cloud Storage Java API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

您可以通过将 AllowParallelCompositeUpload 设置为 true 来执行并行复合上传。 例如：

import com.google.cloud.storage.transfermanager.ParallelUploadConfig;
import com.google.cloud.storage.transfermanager.TransferManager;
import com.google.cloud.storage.transfermanager.TransferManagerConfig;
import com.google.cloud.storage.transfermanager.UploadResult;
import java.io.IOException;
import java.nio.file.Path;
import java.util.List;

class AllowParallelCompositeUpload {

  public static void parallelCompositeUploadAllowed(String bucketName, List<Path> files)
      throws IOException {
    TransferManager transferManager =
        TransferManagerConfig.newBuilder()
            .setAllowParallelCompositeUpload(true)
            .build()
            .getService();
    ParallelUploadConfig parallelUploadConfig =
        ParallelUploadConfig.newBuilder().setBucketName(bucketName).build();
    List<UploadResult> results =
        transferManager.uploadFiles(files, parallelUploadConfig).getUploadResults();
    for (UploadResult result : results) {
      System.out.println(
          "Upload for "
              + result.getInput().getName()
              + " completed with status "
              + result.getStatus());
    }
  }
}

Node.js

如需了解详情，请参阅 Cloud Storage Node.js API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

Node.js 客户端库不支持并行复合上传。请改用 XML API 分段上传。

Python

如需了解详情，请参阅 Cloud Storage Python API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

Python 客户端库不支持并行复合上传。请改用 XML API 分段上传。

REST API

JSON API 和 XML API 都支持并行上传对象数据块，并且支持使用 compose 操作将它们重新组合为单个对象。

为并行复合上传设计代码时，请注意以下几点：

  • 使用 compose 操作时，源对象不受组合过程的影响。

    这意味着，如果您希望它们暂时存在，则顺利完成组合后您必须明确删除它们，否则源对象会保留在存储桶中并因此而产生费用。

  • 为了防止源对象在上传请求和组合请求之间发生更改，您应为每个源对象提供一个预期的世代编号。