並列複合アップロード

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

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

アップロードされたオブジェクトに MD5 ハッシュが必要ない場合。
オブジェクトをダウンロードする必要のある Python ユーザー（gsutil ユーザーを含む）が、google-crc32c または crcmod をインストール済みの場合。

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

警告: 並列複合アップロードでは、アップロード直後に一時オブジェクトが削除されます。ただし、次の点にご注意ください。

一時オブジェクトには必ず Standard ストレージを使用してください。他のストレージクラスには早期削除料金が適用されます。最終的なオブジェクトが完成した後は、ストレージクラスを変更できます。
保持ポリシーがあるバケットにアップロードする場合は、並列複合アップロードを使用しないでください。保持期間が終了するまで一時オブジェクトが削除できなくなります。
アップロード先バケットでデフォルトのオブジェクト保留が有効になっている場合、削除する前に、各一時オブジェクトから保留を解除する必要があります。

ツールと 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 は、次のすべての条件を満たす場合にのみ並列複合アップロードを実行します。
- アップロードされたオブジェクトのストレージクラスが STANDARD になっている。
- 転送先バケットに保持ポリシーがない。
- 転送先バケットでデフォルトのオブジェクト保持が有効になっていない。
なお、これらの条件を確認するために、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 のリファレンスドキュメントをご覧ください。

Node.js クライアントライブラリは、並列複合アップロードをサポートしていません。代わりに、XML API マルチパートアップロードを使用します。

Python

詳細については、Cloud Storage Python API のリファレンスドキュメントをご覧ください。

Python クライアントライブラリは、並列複合アップロードをサポートしていません。代わりに、XML API マルチパートアップロードを使用します。

REST API

JSON API と XML API では、オブジェクトチャンクを並行してアップロードし、compose オペレーションで単一のオブジェクトに統合できます。

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

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

つまり、一時オブジェクトは統合が正常に完了した後に明示的に削除する必要があります。そうしないと、ソースオブジェクトがバケットに残り、課金されます。
アップロードリクエストと作成リクエストの間に、ソースオブジェクトが変更されないようにするためには、各ソースに予想される世代番号を付与する必要があります。