XML API マルチパート アップロード

このページでは、Cloud Storage での XML API マルチパート アップロードについて説明します。このアップロード メソッドでは、ファイルを分割してアップロードし、最終リクエストを使用して単一のオブジェクトにまとめます。XML API マルチパート アップロードは、Amazon S3 マルチパート アップロードと互換性があります。

概要

XML API マルチパート アップロードを使用すると、データを複数のパートでアップロードし、最終的なオブジェクトにできます。特に大きなファイルの場合、この動作にはいくつかのメリットがあります。

  • 同時にパートをアップロードすることで、データ全体のアップロード時間を短縮できます。

  • いずれかのアップロード処理が失敗した場合、最初からやり直すのではなく、オブジェクト全体の中の一部を再アップロードするだけで済みます。

  • 合計ファイルサイズは事前に指定されないため、XML API マルチパート アップロードは、ストリーミング アップロードまたはアップロード中のデータ圧縮に使用できます。

XML API マルチパート アップロードには、必要な 3 つのステップがあります。

  1. POST リクエストを使用してアップロードを開始します。このリクエストには、完了したときにオブジェクトが持つメタデータを指定します。レスポンスでは、アップロードに関連付けられた後続のすべてのリクエストで使用する UploadId が返されます。

  2. 1 つ以上の PUT リクエストを使用してデータをアップロードします。

  3. POST リクエストを使用してアップロードを完了します。このリクエストは、同じ名前を持つバケット内の既存のオブジェクトを上書きします。

マルチパート アップロードとアップロードされたパーツが、バケット内で未完成状態やアイドル状態になっている時間に上限はありません。

考慮事項

XML API マルチパート アップロードを使用する場合、次の制限が適用されます。

  • パートの最小サイズと最大サイズ、完了したアップロードの構成に使用できるパートには、上限があります。
  • 前提条件はリクエストでサポートされません。
  • この方法でアップロードされたオブジェクトには、MD5 ハッシュは存在しません。
  • このアップロード方法は、Google Cloud コンソールまたは Google Cloud CLI ではサポートされていません。

XML API マルチパート アップロードを使用する場合は、次の点に注意してください。

  • XML API マルチパート アップロードには、特定の IAM 権限があります。カスタム IAM ロールを使用する場合は、これらのロールに必要な権限が付与されていることを確認してください。

  • アップロードの開始とパートのアップロードを行うことはできますが、リクエストが記録保持または未完成保持期間を持つオブジェクトを上書きする場合、アップロード完了のリクエストはエラーになります。

  • バケットで実行中のアップロードを一覧表示することもできますが、完了したアップロードだけがバケット内の通常のオブジェクト リストに表示されます。

  • アップロードしたパートが使用されなかった場合、早期削除料金の対象となることがあります。

クライアント ライブラリで XML API マルチパート アップロードを使用する方法

このセクションでは、XML API マルチパート アップロードをサポートするクライアント ライブラリを使用してアップロードを行う方法について説明します。

クライアント ライブラリ

Java

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

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

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

Node.js

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

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

XML API マルチパート アップロードは、uploadFileInChunks メソッドを使用して実行できます。例:

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

XML API マルチパート アップロードは、upload_chunks_concurrently メソッドを使用して実行できます。例:

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}.")

次のステップ