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

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

概要

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

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

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

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

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

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

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

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

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

  • 中止されたマルチパート アップロードの蓄積を防ぐには、オブジェクトのライフサイクル管理を使用して、指定された期間に達したときにマルチパート アップロードを自動的に削除します。
  • 考慮事項

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

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

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

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

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

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

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

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

    クライアント ライブラリ

    Java

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

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

    コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

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

    Node.js

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

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

    コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

    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 filePath = '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 に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。

    コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

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

    次のステップ