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

このページでは、ストリートビュー 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. リクエストを送信します。

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

次の例は、新しいファイルをアップロードするために再開可能なセッションを開始する方法を示しています。この場合、ファイルは画像で、ファイルの合計バイト数は 4,200,000 です。リクエストの本文は空であるため、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. 単一のリクエストで。通常、この方法が最適です。リクエストの数が少なく、パフォーマンスが向上するためです。
  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（メビバイト）の倍数である 2,097,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 でない場合は、アップロードがすでに終了しています。