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 多部分上傳的用戶端程式庫執行這項作業。

用戶端程式庫

Java

詳情請參閱 Cloud Storage Java API 參考說明文件。

如要驗證 Cloud Storage，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

Java 用戶端程式庫不支援 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 filePath = '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}.")


if __name__ == "__main__":
    argparse = argparse.ArgumentParser(
        description="Upload a file to GCS in chunks concurrently."
    )
    argparse.add_argument(
        "--bucket_name", help="The name of the GCS bucket to upload to."
    )
    argparse.add_argument(
        "--source_filename", help="The local path to the file to upload."
    )
    argparse.add_argument(
        "--destination_blob_name", help="The name of the object in GCS."
    )
    argparse.add_argument(
        "--chunk_size",
        type=int,
        default=32 * 1024 * 1024,
        help="The size of each chunk in bytes (default: 32 MiB). The remote\
              service has a minimum of 5 MiB and a maximum of 5 GiB",
    )
    argparse.add_argument(
        "--workers",
        type=int,
        default=8,
        help="The number of worker processes to use (default: 8).",
    )
    args = argparse.parse_args()
    upload_chunks_concurrently(
        args.bucket_name,
        args.source_filename,
        args.destination_blob_name,
        args.chunk_size,
        args.workers,
    )

後續步驟