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

このページでは、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. 単一のリクエストで通常はこの方法が最適です。リクエストの数が少なく、パフォーマンスが向上します。
  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 を繰り返します。

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

単一リクエスト

次の例は、前の手順で取得した再開可能なセッション URI を使用して、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

このオフセットでアップロードを再開できます。再開する場合は、サーバーから提供されたオフセットで行う必要があります。ただし、upload コマンドと finalize コマンドを組み合わせて送信する場合は、オフセットを 0 で再開することもできます。

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