平行複合式上傳

平行複合式上傳是上傳大型檔案的一種策略。在這種上傳作業中，檔案會分割成最多 32 個區塊，這些區塊會平行上傳至臨時物件，最終物件會使用臨時物件重新建立，然後刪除臨時物件。

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

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

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

    舉例來說，如果您使用 Python 上傳只由 Java 應用程式提供的影片資產，並行複合上傳功能就很適合，因為 Java 有提供高效的 CRC32C 實作功能。

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

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

控制台

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

指令列

您可以修改下列屬性，設定 gcloud storage cp 執行平行複合式上傳的方式和時機：

  • storage/parallel_composite_upload_enabled：啟用平行組合上傳功能的屬性。如果是 False，請停用平行複合式上傳功能。如果是 True 或 None，則針對符合其他屬性中定義的條件，為物件執行平行複合上傳作業。預設為 None。

  • storage/parallel_composite_upload_compatibility_check：用於切換安全性檢查的屬性。如果為 True，gcloud storage 只會在符合下列所有條件時執行平行複合式上傳：

    請注意，為了檢查這些條件，gcloud CLI 會在上傳指令中擷取目的地儲存桶的中繼資料。

    如果為 False，gcloud storage 就不會執行任何檢查。預設設定為 True。

  • 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 和 XML API 都支援並行上傳物件區塊，並使用 compose 作業將這些區塊重新組合為單一物件。

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

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

    也就是說，如果這些物件是暫時性的，您必須在成功完成合成作業後，明確刪除這些物件，否則來源物件會保留在值區中，並依據實際使用量計費。

  • 為了防止在上傳和組合要求之間來源物件發生變更，您應為每個來源提供預期的產生版本號碼。