平行複合式上傳

注意： 如果您透過 XML API 與 Cloud Storage 互動，建議使用 XML API 分割上傳，而非平行複合上傳：XML API 分割上傳支援的分割數量比 compose 作業多，產生提早刪除費用的可能性較低，且最終物件組合完成後，不需要 Delete 要求即可移除來源分割。

上傳大型檔案的其中一種策略稱為「平行複合上傳」。在這類上傳作業中，檔案最多會分割成 32 個區塊，這些區塊會平行上傳至暫存物件，最終物件會使用暫存物件重新建立，而暫存物件則會刪除。

如果網路和磁碟速度不是限制因素，平行複合上傳的速度可能會大幅提升；不過，儲存在 bucket 中的最終物件是複合式物件，只有 crc32c 雜湊，沒有 MD5 雜湊。因此，使用 Python 應用程式下載物件時，必須使用 crcmod 執行完整性檢查。只有在符合下列條件時，才應執行平行複合上傳：

• 上傳的物件不一定要有 MD5 雜湊。

• 任何需要下載物件的 Python 使用者 (包括 gsutil 使用者) 都已安裝 google-crc32c 或 crcmod。

  舉例來說，如果您使用 Python 上傳僅由 Java 應用程式提供的影片素材資源，平行複合上傳就是不錯的選擇，因為 Java 提供有效率的 CRC32C 實作。

警告： 平行複合上傳會刪除暫時物件。請注意下列事項：

• 如要盡可能減少暫存物件的費用，請在組合過程中實刪除暫存物件。
• 如果您打算在組合程序完成後刪除暫時物件，請使用Standard Storage儲存暫時物件，以免因其他儲存空間級別而產生提早刪除費用。最終物件組成後，您可以變更其儲存空間級別。
• 如果 bucket 啟用了虛刪除或物件版本管理等資料保護功能，在組成程序完成後刪除暫存物件，可能會大幅增加儲存空間費用。如果您經常執行平行複合上傳作業，請考慮在 Bucket 上停用這些保護措施。或者，您也可以在組成過程中，實刪除暫存物件。
• 如果上傳的目的地 bucket 設有資料保留政策，請勿使用平行複合上傳功能，因為暫存物件必須等到保留期限過後才能刪除。
• 如果上傳的 bucket 已啟用預設物件保留，您必須先解除保留每個暫時物件，才能刪除。

必要的角色

如要取得執行平行複合上傳所需的權限，請要求管理員授予您 bucket 的 Storage 物件使用者 (roles/storage.objectUser) IAM 角色。

Storage 管理員 (roles/storage.admin) 角色具備上傳、讀取和刪除物件區塊所需的權限。此外，這個角色也包含 gcloud CLI 執行儲存空間層級相容性檢查所需的權限，可與平行複合上傳作業搭配使用。如果無法取得 Storage 管理員 (roles/storage.admin) 角色，您仍可使用 gcloud CLI 執行平行複合上傳，方法是取得 Storage 物件使用者 (roles/storage.objectUser) 角色，並停用 storage/parallel_composite_upload_compatibility_check 屬性。詳情請參閱「工具和 API 如何使用平行複合上傳」一節中的「指令列」分頁。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

如需如何授予 bucket 角色的操作說明，請參閱「在 bucket 上設定及管理 IAM 政策」。

工具和 API 如何使用平行複合上傳

視您與 Cloud Storage 的互動方式而定，系統可能會自動為您管理平行複合上傳作業。本節說明不同工具的平行複合上傳行為，並提供如何修改行為的資訊。

控制台

Google Cloud 控制台不會執行平行複合上傳。

指令列

下列屬性會共同決定 gcloud CLI 執行平行複合上傳的方式和時機：

• storage/parallel_composite_upload_enabled：啟用平行複合上傳的屬性。如果為 False，則會停用並行複合上傳作業，並略過 bucket 層級的相容性檢查。如果為 True 或 None，則會為符合其他屬性定義條件的物件啟用平行複合上傳功能，並啟用相容性檢查。預設為 None。

• storage/parallel_composite_upload_compatibility_check：用於切換值區層級檢查的屬性，可檢查與平行複合上傳作業的相容性和安全性。如果設為 True，gcloud CLI 會先傳送 GET 要求，取得目的地 bucket 的中繼資料，再嘗試平行複合上傳，因此主體必須具備 storage.buckets.get 權限。只有在符合下列所有條件時，gcloud CLI 才會執行平行複合上傳：

  • 上傳物件的儲存空間級別為 STANDARD。
  • 目的地 bucket 沒有資料保留政策。
  • 目的地 bucket 未啟用預設物件保留。

  預設為 True。如果為 False，gcloud CLI 就不會執行相容性檢查。

  將 storage/parallel_composite_upload_compatibility_check 設為 False 不會停用平行複合上傳功能。如果 storage/parallel_composite_upload_compatibility_check 設為 False，且 storage/parallel_composite_upload_enabled 為 None 或 True，gcloud CLI 會略過 bucket 檢查，直接執行平行複合上傳。

  如要略過這項檢查，請停用 storage/parallel_composite_upload_compatibility_check 屬性：

  gcloud config set storage/parallel_composite_upload_compatibility_check False
  

• 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

JSON API 支援平行上傳物件區塊，並使用 compose 作業將這些區塊重新組合成單一物件。

設計平行複合式上傳的程式碼時，請注意下列事項：

• 使用 compose 作業時，您可以在組合過程中硬刪除來源物件。 如果臨時物件不需要虛刪除或物件版本管理功能保護，請使用這個選項，盡量減少帳單費用。

• 為防止來源物件在上傳和撰寫要求之間發生變更，您應為每個來源提供預期的產生編號。

XML API

XML API 支援平行上傳物件區塊，並使用 compose 作業將這些區塊重組為單一物件。

設計平行複合上傳程式碼時，請注意下列事項：

• 使用 compose 作業時，來源物件不會受到組合程序影響。

  也就是說，如果這些物件只是暫時存在，您必須在成功完成組合後明確刪除這些物件，否則來源物件會保留在 bucket 中，並依此計費。

• 為防止來源物件在上傳和撰寫要求之間發生變更，您應為每個來源提供預期的產生編號。

疑難排解

本節說明如何排解平行複合上傳時可能發生的 gcloud CLI 錯誤。

無法檢查目的地 bucket 是否與平行複合上傳功能相容

問題：使用 gcloud storage cp 或 gcloud storage mv 上傳 150 MiB 以上的檔案時，指令會記錄下列訊息一次，但上傳作業會成功完成，並顯示結束代碼 0：

ERROR: Cannot check if the destination bucket is compatible for running
parallel composite uploads as the user does not permission to perform GET
operation on the bucket. The operation will be performed without parallel
composite upload feature and hence might perform relatively slower.

解決方案：gcloud CLI 嘗試執行平行複合上傳相容性檢查。主體沒有目的地 bucket 的 storage.buckets.get 權限，因此系統拒絕了 bucket 中繼資料的要求。gcloud CLI 會在內部處理錯誤，不會顯示 HTTP 狀態碼。而是記錄訊息，並改為一般上傳。

如要平行上傳複合式檔案，請確認主體在目標 bucket 中具有 storage.buckets.get、storage.objects.get 和 storage.objects.delete 權限。您可以透過 Storage 管理員 (roles/storage.admin) 角色授予這些權限。或者，如果主體已透過「Storage 物件使用者」等角色 (roles/storage.objectUser) 取得 storage.objects.get 和 storage.objects.delete 權限，則可將 storage/parallel_composite_upload_compatibility_check 屬性設為 False，停用相容性檢查。

403：沒有 storage.objects.get 存取權

問題：上傳小於 150 MiB 的檔案會成功，但上傳 150 MiB 以上的檔案會失敗，並顯示結束代碼 1 和類似下列的錯誤：

HTTPError 403: PRINCIPAL does not have storage.objects.get access to
the Google Cloud Storage object.

解決方法：storage/parallel_composite_upload_compatibility_check 設為 False，storage/parallel_composite_upload_enabled 則設為 None 或 True。採用這項設定時，gcloud CLI 會略過 bucket 相容性檢查，直接執行平行複合上傳。

由於主體具有 storage.objects.create 權限，因此臨時物件上傳成功。不過，將臨時物件組合成最終物件需要 storage.objects.get 權限，之後刪除臨時物件則需要 storage.objects.delete 權限。

如要解決這個問題，請選擇下列其中一個選項：

• 如果不需要平行複合上傳，請停用這項功能：

  gcloud config set storage/parallel_composite_upload_enabled False
  

  所有檔案都會以一般上傳方式上傳，主體只需要 Storage 物件建立者 (roles/storage.objectCreator) 角色包含的權限。您可以將其保留 storage/parallel_composite_upload_compatibility_check在任何值。

• 如要進行平行複合上傳作業，請在目的地值區中，將 storage.objects.get 和 storage.objects.delete 權限授予主體。您可以透過 Storage 物件使用者 (roles/storage.objectUser) 角色授予這些權限。

如果上傳失敗導致值區中留下暫存物件，請將其刪除。根據預設，暫時物件會使用前置字串 gcloud/tmp/parallel_composite_uploads/see_gcloud_storage_cp_help_for_details。如要刪除因上傳失敗而產生的暫存物件，您必須具備 storage.objects.delete 權限。

請注意，gcloud storage rsync 指令的行為與 gcloud storage cp 和 gcloud storage mv 不同。如果目的地是儲存空間根目錄 (例如 gs://my-bucket)，無論並行複合上傳設定為何，gcloud storage rsync 一律需要 storage.buckets.get 權限才能同步處理至儲存空間。如果目的地是 bucket 子目錄 (例如 gs://my-bucket/dir/)，只要在平行複合上傳設定中停用相容性檢查，gcloud storage rsync 就不需要 storage.buckets.get 權限。在這種情況下，gcloud storage rsync 需要 storage.objects.get 權限，而非 storage.buckets.get。