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}.")

後續步驟