このページは Cloud Translation API によって翻訳されました。

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

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

概要

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

同時に部分をアップロードすることで、データ全体のアップロード時間を短縮できます。
いずれかのアップロード処理が失敗した場合、最初からやり直すのではなく、オブジェクト全体の中の一部を再アップロードするだけで済みます。
合計ファイルサイズは事前に指定されないため、XML API マルチパートアップロードは、ストリーミングアップロードまたはアップロード中のデータ圧縮に使用できます。

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

POST リクエストを使用してアップロードを開始します。このリクエストには、完了したときにオブジェクトが持つメタデータを指定します。レスポンスでは、アップロードに関連付けられた後続のすべてのリクエストで使用する UploadId が返されます。
1 つ以上の PUT リクエストを使用してデータをアップロードします。
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 のリファレンスドキュメントをご覧ください。

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 のリファレンスドキュメントをご覧ください。

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

次のステップ

Cloud Storage のその他のアップロード方法を確認する。
切り捨て型指数バックオフと、リクエストを再試行するタイミングについて学習する。