並列複合アップロード

サイズの大きいファイルをアップロードする方法の一つとして並列複合アップロードがあります。このアップロードでは、1 つのファイルが最大で 32 チャンクに分割され、これらのチャンクが並列して一時オブジェクトにアップロードされます。これらのオブジェクトから最終的なオブジェクトが作成され、一時オブジェクトが削除されます。

ネットワークとディスクの速度が制限されていなければ、並列複合アップロードは非常に高速になります。ただし、バケットに保存される最終オブジェクトは複合オブジェクトになります。このオブジェクトは crc32c ハッシュのみとなり、MD5 ハッシュはありません。そのため、Python アプリケーションでオブジェクトをダウンロードするときに、crcmod を使用して完全性検査を実施する必要があります。並列複合アップロードは、次の場合に限り使用します。

  • オブジェクトをダウンロードする必要のある Python ユーザー(gsutil ユーザーを含む)が、google-crc32c または crcmod をインストールしている。

    たとえば、Java アプリケーションからのみ配信される動画アセットを Python でアップロードする場合は、Java で CRC32C を効率的に実装できるため、並列複合アップロードが適しています。

  • アップロードされたオブジェクトに MD5 ハッシュは必要ありません。

ツールと 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 に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。

AllowParallelCompositeUploadtrue に設定すると、並列複合アップロードを行うことができます。例:

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 APIXML API では、オブジェクト チャンクを並行してアップロードし、compose オペレーションで単一のオブジェクトに統合できます。

並列複合アップロードのコードを設計する場合は次の点に注意してください。

  • compose オペレーションを使用する場合、ソース オブジェクトは作成処理の影響を受けません。

    つまり、一時オブジェクトは統合が正常に完了した後に明示的に削除する必要があります。そうしないと、ソース オブジェクトがバケットに残り、課金されます。

  • アップロード リクエストと作成リクエストの間に、ソース オブジェクトが変更されないようにするためには、各ソースに予想される世代番号を付与する必要があります。