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 雜湊。
    • Trusted Cloud 控制台或 Google Cloud CLI 不支援這種上傳方法。

    使用 XML API 多部分上傳時，請注意下列事項：

    用戶端程式庫如何使用 XML API 多部分上傳作業

    本節說明如何使用支援 XML API 多部分上傳的用戶端程式庫執行這項作業。

    用戶端程式庫

    Java

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

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

    執行程式碼範例前，請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。

    Java 用戶端程式庫不支援 XML API 多部分上傳。請改用平行複合式上傳。

    Node.js

    詳情請參閱 Cloud Storage Node.js API 參考說明文件。

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

    執行程式碼範例前，請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。

    您可以使用 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，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

    執行程式碼範例前，請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。

    您可以使用 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}.")

    後續步驟