再開可能なアップロード

サンプルに移動

このページでは、JSON API と XML API での Cloud Storage の再開可能なアップロードについて説明します。再開可能なアップロードでは、ネットワーク障害が発生した場合に大容量のファイルのアップロードを最初からやり直す必要がないため、使用する帯域幅を削減できます。完了した再開可能なアップロードは、1 つのクラス A オペレーションとみなされます。

概要

Cloud Storage には再開可能なデータ転送機能があり、通信障害によってデータのフローが中断しても、その後アップロード オペレーションを再開できます。再開可能なアップロードは、大容量のファイルを転送する際に便利です。大容量のファイルはネットワークの中断やその他の送信エラーが起こる可能性が高いからです。再開可能なアップロード機能を使用することで、大容量のファイルのアップロードを最初からやり直す必要がなくなり、使用する帯域幅（したがって帯域幅のコスト）を削減できます。Cloud Storage にアップロードするためのヒントについては、ベスト プラクティスをご覧ください。

Cloud Storage JSON API と XML API ではデータをアップロードするために、POST Object と PUT Object の 2 つの標準 HTTP メソッドを用意しています。再開可能なアップロードを実装するには、この 2 つのメソッドをさまざまなヘッダーやクエリ文字列パラメータと組み合わせて使用します。

信頼性が高いネットワーク接続でサイズの小さなファイルを送信する場合は、シンプルなアップロードを使用できます。

リクエスト URI の詳細

JSON API を使用してオブジェクトをアップロードする場合は、ほとんどの JSON API リクエスト（オブジェクトのメタデータのアップロード リクエストなど）とは異なる特別な URI を使用します。

  • オブジェクトのアップロードの場合は、/upload URI を使用します。/upload エンドポイントの形式は、標準リソース URI に「/upload」接頭辞を付けたものです。この URI は、オブジェクト データ自体を転送するときに使用します。

    たとえば、myBucket という名前のバケットです。

    POST /upload/storage/v1/b/myBucket/o

  • 他のリクエストには、標準リソース URI を使用します。これには、既存のオブジェクトのメタデータ値の追加または更新が含まれます。

    たとえば、myBucket という名前のバケット内の myObject という名前のオブジェクトへのメタデータ パッチの場合:

    PATCH /storage/v1/b/myBucket/o/myObject

XML のコンテンツ タイプ

アップロードするファイルのコンテンツ タイプを指定する場合は、Content-Type リクエスト ヘッダーを含めることが可能です。コンテンツ タイプを指定しないと、Cloud Storage システムはでは、アップロードしたオブジェクトを提供するときに、コンテンツ タイプが application/octet-stream に設定されます。

x-goog-resumable ヘッダーは Cloud Storage の拡張（カスタム）ヘッダーです。このヘッダーでは、再開可能なアップロードを開始することを Cloud Storage システムに通知します。このヘッダーは、POST Object リクエストを使用して再開可能なアップロードを開始する場合にのみ使用できます。

さらに、リクエスト内で標準の Cloud Storage ホスト名を使用し、他の認証リクエストと同じように POST Object リクエストを認証する必要があります。詳細については、リクエスト エンドポイントと認証をご覧ください。

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

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

おすすめのヒント

  • セッション URI は 1 週間後に期限切れになります。セッション URI を取得したらすぐに再開可能なアップロードを開始すること、また、中断が発生したらすぐにそのアップロードを再開することをおすすめします。

  • 期限切れになったセッション URI をリクエストで使用すると、400 Bad Request ステータス コードが返されます。この場合は、再開可能なアップロードを新たに開始して新しいセッション URI を取得し、新しいセッション URI を使用してアップロードを最初からやり直す必要があります。

  • 再開可能なアップロード セッションを開始すると、アップロードの作成と再開に使用するセッション URI が返されます。このセッション URI は認証トークンとして機能するため、PUT リクエストに署名する必要はありません。それ以降は認証なしにターゲット バケットにデータをアップロードできるため、セッション URI の共有は慎重に行い、HTTPS 経由でのみ転送してください。

  • また、次のステータス コードが返された場合は、リクエストを再試行する必要があります。

    • 408 Request Timeout
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout

  • 再開可能なアップロードで 404 Not Found エラーが発生した場合には、最初から全体のアップロードをやり直してこのエラーを処理してください。

リクエストを再試行する場合は、切り捨てられた指数バックオフを使用します。

  • さらに、最終的にアップロードされたオブジェクトの整合性をチェックして、ソースファイルと一致するかどうかを確認することをおすすめします。これを行うには、ソースファイルの MD5 ダイジェストを計算し、その値を Content-MD5 レスポンス ヘッダーの値と比較します。アップロードされたファイルの整合性をチェックすることは、大容量のファイルを長時間かけてアップロードするときに特に重要です。ソースファイルがアップロード操作の過程で変更される可能性が高いからです。

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

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

オプションの最適化

Range ヘッダーなしの 308 Resume Incomplete レスポンスを受信した場合、一部のバイトが Cloud Storage で受信されたものの、Cloud Storage でクエリを受信した時点ではまだ永続化されていない可能性があります。 この場合、ファイルの先頭から再送信すると、やや効率が低くなります。 このような可能性を減らすには、最初の 308 レスポンスの後、数秒待ってから、2 回目のクエリを行います。その時点で Range ヘッダーを受信し、ファイルの先頭から再送信することを回避できます。この 2 回目の試行で Range ヘッダーを受信しない場合は、Cloud Storage で実際にはアップロードされたデータを受信していない場合に再クエリを続行すると、アップロードが「ハング」する可能性があるため、それ以上待たずに 3 回目の試行を行ってください。

次のステップ