再開可能なアップロードの実行

このページでは、Street View Publish API で再開可能なアップロード リクエストを行う方法について説明します。このプロトコルを使用すると、通信障害でデータの送信が中断しても、アップロード操作を再開できます。このオプションは、次の場合に使用します。

  • サイズの大きいファイルをアップロードする場合。
  • ネットワークの中断やその他の送信障害が発生する可能性が高い（モバイルアプリからファイルをアップロードしている場合など）。

再開可能なアップロードでは、ネットワーク障害が発生したときに、サイズの大きなファイルのアップロードを最初からやり直す必要がないため、帯域幅の消費を減らすことができます。

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

再開可能なアップロードのセッションを開始する

uploadUrl を取得したら、再開可能なアップロード セッションを開始できます。

  1. uploadUrl に対する POST リクエストを作成します。

  2. 次の HTTP ヘッダーを追加します。

    • X-Goog-Upload-Protocol: resumable に設定します。
    • X-Goog-Upload-Header-Content-Length: 後続のリクエストで転送されるファイルデータの合計バイト数に設定します。
    • X-Goog-Upload-Header-Content-Type: ファイルデータの MIME タイプに設定します。
    • X-Goog-Upload-Command: start に設定します。

  3. リクエストを送信します。

例: 再開可能なアップロードのセッションを開始する

次の例は、再開可能セッションを開始して新しいファイルをアップロードする方法を示しています。この場合、ファイルは画像で、ファイルの合計バイト数は 4200000 です。リクエストの本文は空であるため、Content-Length ヘッダーは 0 に設定されます。

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234 HTTP/1.1
Authorization: Bearer [YOUR_AUTH_TOKEN]
Content-Length: 0
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Header-Content-Length: 4200000
X-Goog-Upload-Header-Content-Type: image/jpeg
X-Goog-Upload-Command: start

再開可能セッションの URL の保存では、再開可能なアップロード セッションを開始するリクエストのレスポンスを処理する方法について説明しています。

再開可能セッションの URL の保存

再開可能なアップロード セッションを開始するために送信されたリクエストに対して、サーバーは次のヘッダーを含む 200 OK HTTP ステータス コードを返します。

  • X-Goog-Upload-URL: 残りのすべてのリクエストでアップロードを完了するために使用される一意の URL。

後続のリクエストで使用できるように、再開可能な URL をコピーして保存します。

例: 再開可能セッションの URL の保存

次の例は、再開可能なセッションの URL とサイズ粒度の要件を含むレスポンスを示しています。

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable

ファイルをアップロードする

再開可能なセッションでファイルをアップロードするには、2 つの方法があります。

  1. 1 回のリクエストで行う。通常、このアプローチはリクエストが少なくなり、パフォーマンスが向上するため、最適です。
  2. 複数のチャンク。 この方法は、次の場合に使用してください。
    • 1 回のリクエストで転送するデータの量を減らす必要があります。個々のリクエストに一定の時間制限がある場合は、この操作が必要になることがあります。
    • アップロードの進行状況を表すカスタム インジケーターが必要な場合。
    • データを安全に破棄できるタイミングを知る必要があります。

単一のリクエスト

ファイルを単一リクエストでアップロードするには:

  1. 再開可能セッションの URL に対する POST リクエストを作成します。
  2. ファイルのデータをリクエストの本文に追加します。

  3. 次の HTTP ヘッダーを追加します。

    • Content-Length: ファイルのバイト数に設定します。
    • X-Goog-Upload-Command: upload, finalize に設定します。

  4. リクエストを送信します。

アップロード リクエストが中断された場合、または 5xx レスポンスが返された場合は、中断されたアップロードを再開するの手順を行ってください。

複数のチャンク

複数のチャンクでファイルをアップロードするには:

  1. 再開可能セッションの URL に対する POST リクエストを作成します。
  2. リクエストの本文にチャンクのデータを追加します。アップロードを完了する最終的なチャンクを除き、2 MiB（メビバイト）の倍数のチャンクを作成します。アップロードが効率的に行われるように、チャンクサイズは可能な限り大きくしてください。

  3. 次の HTTP ヘッダーを追加します。

    • Content-Length: チャンク内のバイト数に設定します。
    • X-Goog-Upload-Command: upload に設定します。最後のチャンクには、upload, finalize に設定します。
    • X-Goog-Upload-Offset: バイトを書き込むオフセットに設定します。バイトは順番にアップロードする必要があります。

  4. リクエストを送信します。 アップロード リクエストが中断された場合、または 5xx レスポンスが返された場合は、中断されたアップロードを再開するの手順に沿って操作します。

  5. ファイルに残っているチャンクごとに、手順 1 ～ 4 を繰り返します。

例: ファイルをアップロードする

単一のリクエスト

次の例は、前の手順で取得した再開可能セッションの URL を使用して、4,200,000 バイトの JPEG ファイルを 1 回のリクエストでアップロードする再開可能リクエストを示しています。

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 4200000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

リクエストが成功すると、200 OK HTTP ステータス コードが返されます。

複数のチャンク

次の例は、再開可能セッションの URL と前の手順で取得したサイズの粒度を使用して、4,200,000 バイトの JPEG ファイルを複数のチャンクでアップロードする再開可能リクエストを示しています。この例では、2 MiB（メビバイト）の倍数である 2097, 000 バイトのチャンクサイズを使用しています。

最初のチャンク:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0



[BYTES 0-2096999]

2 番目のチャンク:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 2097000



[BYTES 2097000-4193999]

最後のチャンク:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 6000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 4194000



[BYTES 4194000-4200000]

中断されたアップロードの再開

アップロード リクエストが中断した場合、または 200 以外の HTTP ステータス コードを受け取った場合は、サーバーにクエリして、アップロードがどの程度成功したかを確認します。

  1. 再開可能セッションの URL に対する POST リクエストを作成します。
  2. X-Goog-Upload-Command を query に設定します。
  3. リクエストを送信します。

サーバーは 200 OK HTTP ステータス コードとアップロードの現在のサイズを返します。

HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-Size-Received: 100

その後、このオフセットでアップロードを再開できます。アップロードとファイナライズを組み合わせたコマンドを送信する場合を除き、サーバーから提供されたオフセットから再開する必要があります。この場合、オフセット 0 から再開することもできます。

クエリコマンドの HTTP レスポンスに X-Goog-Upload-Status ヘッダーが存在し、その値が active でない場合、アップロードはすでに終了しています。