XML API 分段上传

本页面介绍了 Cloud Storage 中的 XML API 分段上传。这种上传方法会将文件分批上传，然后使用最终请求将它们组合成单个对象。XML API 分段上传与 Amazon S3 分段上传兼容。

概览

XML API 分段上传允许您上传多个部分中的数据，然后将其组合成最终对象。此行为具有多项优势，尤其是对于大型文件：

  • 您可以同时上传多个部分，从而缩短完整上传数据所需的时间。

  • 如果其中一项上传操作失败，您只需重新上传整个对象的一部分，而不必从头开始。

  • 由于没有事先指定总文件大小，因此您可以使用 XML API 分段上传进行流式上传或在上传过程中即时压缩数据。

使用 XML API 分段上传功能时，您需要执行以下三个步骤：

  1. 使用 POST 请求（其中包括指定已完成对象应具有的任何元数据）启动上传。响应会返回一个 UploadId，供您在与上传关联的所有后续请求中使用。

  2. 使用一个或多个 PUT 请求上传数据。

  3. 使用 POST 请求完成上传。此请求将覆盖存储桶中具有相同名称的任何现有对象。

分段上传及其上传的部分可以在存储桶中保持未完成或空闲的时长没有限制。

注意事项

以下限制适用于使用 XML API 分段上传功能：

  • 一个分段的大小下限、大小上限以及用于组成已完成上传的分段的数量均有限制。
  • 请求不支持前提条件。
  • 使用此方法上传的对象不存在 MD5 哈希值。
  • Google Cloud 控制台或 Google Cloud CLI 不支持此上传方法。

使用 XML API 分段上传功能时，请注意以下事项：

客户端库如何使用 XML API 分段上传

本部分介绍如何使用支持 XML API 分段上传的客户端库来执行上传。

客户端库

Node.js

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

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

您可以使用 uploadFileInChunks 方法执行 XML API 分段上传。例如：

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The path of file to upload
// const fileName = 'path/to/your/file';

// The size of each chunk to be uploaded
// const chunkSize = 32 * 1024 * 1024;

// Imports the Google Cloud client library
const {Storage, TransferManager} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

// Creates a transfer manager client
const transferManager = new TransferManager(storage.bucket(bucketName));

async function uploadFileInChunksWithTransferManager() {
  // Uploads the files
  await transferManager.uploadFileInChunks(filePath, {
    chunkSizeBytes: chunkSize,
  });

  console.log(`${filePath} uploaded to ${bucketName}.`);
}

uploadFileInChunksWithTransferManager().catch(console.error);

Python

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

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

您可以使用 upload_chunks_concurrently 方法执行 XML API 分段上传。例如：

def upload_chunks_concurrently(
    bucket_name,
    source_filename,
    destination_blob_name,
    chunk_size=32 * 1024 * 1024,
    workers=8,
):
    """Upload a single file, in chunks, concurrently in a process pool."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The path to your file to upload
    # source_filename = "local/path/to/file"

    # The ID of your GCS object
    # destination_blob_name = "storage-object-name"

    # The size of each chunk. The performance impact of this value depends on
    # the use case. The remote service has a minimum of 5 MiB and a maximum of
    # 5 GiB.
    # chunk_size = 32 * 1024 * 1024 (32 MiB)

    # The maximum number of processes to use for the operation. The performance
    # impact of this value depends on the use case. Each additional process
    # occupies some CPU and memory resources until finished. Threads can be used
    # instead of processes by passing `worker_type=transfer_manager.THREAD`.
    # workers=8

    from google.cloud.storage import Client, transfer_manager

    storage_client = Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(destination_blob_name)

    transfer_manager.upload_chunks_concurrently(
        source_filename, blob, chunk_size=chunk_size, max_workers=workers
    )

    print(f"File {source_filename} uploaded to {destination_blob_name}.")

后续步骤