再開可能なアップロード

サンプルに移動

このページでは、Cloud Storage で再開可能なアップロードについて説明します。大容量のファイルのアップロードには再開可能なアップロードをおすすめします。アップロード中にネットワーク障害が発生した場合に、最初からファイルを再アップロードする必要はありません。

はじめに

再開可能なアップロードを使用すると、通信障害によってデータのフローが中断しても、Cloud Storage へのデータ転送オペレーションを再開できます。再開可能なアップロードでは、リクエストごとにアップロードするオブジェクトの一部が含まれる複数のリクエストを送信できます。これは、1 つのリクエストにオブジェクト データがすべて含まれ、このリクエストが途中で失敗した場合は最初からやり直す必要がある単一リクエストのアップロードとは異なります。

  • 再開可能なアップロードは、大容量のファイルをアップロードする場合や、低速の接続でアップロードする場合に使用してください。たとえば、再開可能なアップロードを使用する際のファイルサイズのカットオフについては、アップロード サイズに関する考慮事項をご覧ください。

  • 再開可能なアップロードは、開始してから 1 週間以内に完了する必要があります。

  • 完了した再開可能なアップロードのみがバケットに表示されます。同じ名前のオブジェクトがすでに存在する場合は、既存のオブジェクトが置き換えられます。

  • 完了した再開可能なアップロードは、1 つのクラス A オペレーションとみなされます。

ツールと API で再開可能なアップロードがどのように使用されるか

Cloud Storage の操作方法によっては、再開可能なアップロードが自動的に管理されることがあります。詳しくは、次の表のタブをクリックしてください。

Console

Cloud Console では、再開可能なアップロードを自動的に管理します。ただし、アップロードの進行中に Cloud Console で更新または移動を行うと、アップロードはキャンセルされます。

gsutil

gsutil コマンドライン ツールで Cloud Storage にデータをアップロードする場合、gsutil cp コマンドと gsutil rsync コマンドで再開可能なアップロードを使用します。アップロードが中断した場合は、アップロードを開始する際に使用した同じコマンドを実行すると再開できます。複数のファイルを含む gsutil cp アップロードを再開する場合は、すでに正常に完了したファイルが再アップロードされないように -n フラグを使用します。

boto 構成ファイルの resumable_threshold パラメータに、再開可能なアップロードの実行に使用される最小サイズを設定できます。resumable_threshold のデフォルト値は 8 MiB です。

クライアント ライブラリ

C++

再開可能なアップロードは、WriteObject メソッドの一部として切り替えることができます。

C#

CreateObjectUploader で再開可能なアップロードを開始できます。

Go

デフォルトでは、ファイルが 16 MiB を超えると、再開可能なアップロードが自動的に行われます。Writer.ChunkSize を使用して再開可能なアップロードを実行する場合のカットオフを変更します。Go クライアント ライブラリを使用すると、再開可能なアップロードは常にチャンク形式となります。

Java

再開可能なアップロードは、writer メソッドによって制御されます。あるいは、createFrom メソッドを使用して、再開可能なアップロードのカットアウト サイズを指定することもできます。

Node.js

createWriteStream メソッドを使用している場合、再開可能なアップロードは自動的に管理されます。

PHP

再開可能なアップロードは自動的に管理されますが、resumable オプションを使用すると直接制御できます。

Python

ファイルが 8 MiB より大きい場合、再開可能なアップロードが自動的に行われます。再開可能なメディアを使用して、再開可能なアップロードを自分で管理することもできます。

Ruby

アップロードはすべて、再開可能なアップロードとして扱われます。

REST API

JSON API

Cloud Storage JSON API は、クエリ パラメータ uploadType=resumable を含む POST Object リクエストを使用して再開可能なアップロードを開始します。このリクエストは、セッション URI として返され、その後 1 つ以上の PUT Object リクエストでオブジェクト データをアップロードするために使用します。再開可能なアップロード用の独自のロジックを作成する詳しい手順については、再開可能なアップロードの実行をご覧ください。

XML API

Cloud Storage XML API は、ヘッダー x-goog-resumable: start を含む POST Object リクエストを使用して再開可能なアップロードを開始します。このリクエストは、セッション URI として返され、その後 1 つ以上の PUT Object リクエストでオブジェクト データをアップロードするために使用します。再開可能なアップロード用の独自のロジックを作成する詳しい手順については、再開可能なアップロードの実行をご覧ください。

不明なサイズの再開可能なアップロード

再開可能なアップロードのメカニズムでは、前もってファイルサイズがわからない場合の転送もサポートしています。これは、アップロード中にオブジェクトを圧縮する場合などに便利です。圧縮したファイルの正確なファイルサイズを転送の開始時点で予測することは難しいからです。このメカニズムは、中断後に再開可能な転送をストリーミングする場合や、チャンク転送エンコードがアプリケーションで機能しない場合に活用できます。

詳細については、ストリーミング転送をご覧ください。

考慮事項

このセクションは、再開可能なアップロード リクエストを JSON または XML API に直接送信する独自のクライアントを構築するのに役立ちます。

セッション URI

再開可能なアップロードを開始すると、Cloud Storage がセッション URI を返します。この URI は、後続のリクエストで使用する実際のデータをアップロードするために使用します。JSON API でのセッション URI の例を次に示します。

https://storage.googleapis.com/upload/storage/v1/b/my-bucket/o?uploadType=resumable&name=my-file.jpg&upload_id=ABg5-UxlRQU75tqTINorGYDgM69mX06CzKO1NRFIMOiuTsu_mVsl3E-3uSVz65l65GYuyBuTPWWICWkinL1FWcbvvOA

XML API でのセッション URI の例を次に示します。

 https://storage.googleapis.com/my-bucket/my-file.jpg?upload_id=ABg5-UxlRQU75tqTINorGYDgM69mX06CzKO1NRFIMOiuTsu_mVsl3E-3uSVz65l65GYuyBuTPWWICWkinL1FWcbvvOA

このセッション URI は認証トークンとして機能するため、このトークンを使用するリクエストには署名の必要がなく、追加の認証を行わずに誰でもそのターゲット バケットにデータをアップロードできます。このため、セッション URI の共有は慎重に行い、HTTPS 経由でのみ共有してください。

セッション URI は 1 週間後に期限切れになりますが、期限切れになる前にキャンセルできます。無効になったセッション URI を使用してリクエストを行うと、次のいずれかのエラーが返されます。

  • 410 Gone ステータス コード。アップロードが開始されてから 1 週間未満の場合。
  • 404 Not Found ステータス コード。アップロードが開始されてから 1 週間以上経過している場合。

いずれの場合でも、再開可能なアップロードを新たに開始して新しいセッション URI を取得し、新しいセッション URI を使用してアップロードを最初からやり直す必要があります。

アップロードのパフォーマンス

再開可能なアップロードは、それを開始したリージョンに固定されます。たとえば、米国で再開可能なアップロードを開始し、アジアのクライアントにセッション URI を渡した場合でも、アップロード自体は米国で実行されます。そのため、再開可能なアップロードを開始したリージョンとは異なるリージョンで続行すると、アップロードに時間がかかる可能性があります。

Compute Engine インスタンスを使用して再開可能なアップロードを開始する場合、インスタンスはアップロード先の Cloud Storage バケットと同じロケーションに存在する必要があります。次に geo IP サービスを使って、顧客のリクエストのルーティング先となる Compute Engine のリージョンを取得することで、地理上の地域にトラフィックを局所化できます。

整合性チェック

最終的にアップロードされたオブジェクトの整合性をチェックして、ソースファイルと一致するかどうかを確認することをおすすめします。これを行うには、ソースファイルの MD5 ダイジェストを計算し、その値を Content-MD5 リクエスト ヘッダーの値と比較します。

アップロードされたファイルの整合性をチェックすることは、大容量のファイルを長時間かけてアップロードするときに特に重要です。ソースファイルがアップロード操作の過程で変更される可能性が高いからです。

データを再送信する

Cloud Storage によって、再開可能なアップロードのバイトが保持されると、それらのバイトは上書きできなくなり、Cloud Storage では上書きの試行が無視されます。そのため、以前に送信したオフセットに逆戻りするときに、別のデータを送信する必要はありません。

たとえば、100,000 バイトのオブジェクトをアップロードし、接続が中断されたとします。ステータスを確認すると、50,000 バイトが正常にアップロードされ、永続化されていることがわかります。40,000 バイトでアップロードを再開しようとすると、Cloud Storage は 40,000 バイト～50,000 バイトで送信されたバイトを無視します。Cloud Storage は、送信したデータの永続化をバイト 50,001 で開始します。

次のステップ