このページでは、Cloud Storage で再開可能なアップロードについて説明します。大容量のファイルのアップロードには再開可能なアップロードをおすすめします。アップロード中にネットワーク障害が発生した場合に、最初からファイルを再アップロードする必要はありません。
はじめに
再開可能なアップロードを使用すると、通信障害によってデータのフローが中断しても、Cloud Storage へのデータ転送オペレーションを再開できます。再開可能なアップロードでは、リクエストごとにアップロードするオブジェクトの一部が含まれる複数のリクエストを送信できます。これは、1 つのリクエストにオブジェクト データがすべて含まれ、このリクエストが途中で失敗した場合は最初からやり直す必要がある単純なアップロードとは異なります。
再開可能なアップロードは、大容量のファイルをアップロードする場合や、低速の接続でアップロードする場合に使用してください。たとえば、再開可能なアップロードを使用する際のファイルサイズのカットオフについては、アップロード サイズに関する考慮事項をご覧ください。
再開可能なアップロードは、開始してから 1 週間以内に完了する必要があります。
完了した再開可能なアップロードのみがバケットに表示されます。同じ名前のオブジェクトがすでに存在する場合は、既存のオブジェクトが置き換えられます。
- オブジェクトの作成時間はアップロードの完了時間に基づきます。
- ユーザーが設定したオブジェクト メタデータは最初のリクエストで指定します。このメタデータは、アップロードの完了時にオブジェクトに適用されます。
完了した再開可能なアップロードは、1 つのクラス A オペレーションとみなされます。
ツールと API で再開可能なアップロードがどのように使用されるか
Cloud Storage を操作する方法によっては、再開可能なアップロードが自動的に管理されることがあります。詳しくは、次の表のタブをクリックしてください。
Console
Cloud Console では、再開可能なアップロードを自動的に管理します。ただし、アップロードの進行中に Cloud Console で更新または移動を行うと、アップロードはキャンセルされます。
gsutil
gsutil コマンドライン ツールで Cloud Storage にデータをアップロードする場合、gsutil cp
コマンドと gsutil rsync
コマンドで再開可能なアップロードを使用します。
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 をリクエストで使用すると、404 Not Found
ステータス コードが返されます。この場合は、再開可能なアップロードを新たに開始して新しいセッション URI を取得し、新しいセッション URI を使用してアップロードを最初からやり直す必要があります。
アップロードのパフォーマンス
再開可能なアップロードは、それを開始したリージョンに固定されます。たとえば、米国で再開可能なアップロードを開始し、アジアのクライアントにセッション URI を渡した場合でも、アップロード自体は米国で実行されます。そのため、再開可能なアップロードを開始したリージョンとは異なるリージョンで続行すると、アップロードに時間がかかる可能性があります。
Compute Engine インスタンスを使用して再開可能なアップロードを開始する場合、インスタンスはアップロード先の Cloud Storage バケットと同じロケーションに存在する必要があります。次に geo IP サービスを使って、顧客のリクエストのルーティング先となる Compute Engine のリージョンを取得することで、地理上の地域にトラフィックを局所化できます。
整合性チェック
最終的にアップロードされたオブジェクトの整合性をチェックして、ソースファイルと一致するかどうかを確認することをおすすめします。これを行うには、ソースファイルの MD5 ダイジェストを計算し、その値を Content-MD5
リクエスト ヘッダーの値と比較します。
アップロードされたファイルの整合性をチェックすることは、大容量のファイルを長時間かけてアップロードするときに特に重要です。ソースファイルがアップロード操作の過程で変更される可能性が高いからです。
次のステップ
- 再開可能なアップロードを行う方法を確認する。
- Cloud Storage にアップロードする際のヒントとベスト プラクティスを確認する。
- 切り捨て型指数バックオフと、リクエストを再試行するタイミングについて学習する。