このページでは、REST プロトコル経由で Google Photos Library API に再開可能なアップロード リクエストを行う方法について説明します。このプロトコルを使用すると、通信障害でデータフローが中断しても、アップロード オペレーションを再開できます。
クライアント ライブラリを使用している場合、一部のクライアント ライブラリでは再開可能なアップロードがネイティブにサポートされています。
次の場合は再開可能アップロード オプションを使用します。
- サイズが大きいファイルをアップロードする場合。
- ネットワークの中断やその他の送信障害が発生する可能性が高い（モバイルアプリからファイルをアップロードする場合など）。
再開可能なアップロードでは、ネットワーク障害が発生したときに、サイズの大きなファイルのアップロードを最初からやり直す必要がないため、帯域幅の消費を減らすことができます。
ステップ 1: アップロード セッションを開始する
https://photoslibrary.googleapis.com/v1/uploads に POST リクエストを送信して、再開可能なアップロード セッションを開始します。このリクエストで返された再開可能なアップロード URL を使用して、ファイルをアップロードします。
POST リクエストには次のヘッダーを含める必要があります。
| ヘッダー フィールド | |
|---|---|
Content-Length |
リクエスト本文が空であるため、0 に設定します。 |
X-Goog-Upload-Command |
start に設定します。 |
X-Goog-Upload-Content-Type |
ファイルの MIME タイプに設定します（例: image/jpeg）。 |
X-Goog-Upload-Protocol |
resumable に設定します。 |
X-Goog-Upload-Raw-Size |
転送するファイルデータの合計バイト数に設定します。 |
POST リクエストのヘッダーは次のようになります。
POST https://photoslibrary.googleapis.com/v1/uploads Authorization: Bearer oauth2-token Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: mime-type X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: bytes-of-file
ステップ 2: セッション URL を保存する
成功すると、POST リクエストは次のヘッダーを含む 200 OK HTTP ステータス コードを返します。
X-Goog-Upload-URL: url-to-make-uploads-to X-Goog-Upload-Chunk-Granularity: chunk-granularity-in-bytes
ヘッダー フィールド x-goog-upload-chunk-granularity には、クライアントから送信されたすべてのデータチャンクのバイト アライメントとサイズ粒度が含まれます。アップロードが複数のチャンクで実行される場合、最後のアップロードを除くすべてのアップロードは、この値の倍数で行う必要があります。つまり、ファイルのアップロード バイトをこの値に合わせる必要があります。最後のチャンクでは、残りのバイトをアップロードできます。
ヘッダー フィールド X-Goog-Upload-URL には一意の URL が含まれています。残りのすべてのリクエストでアップロードを完了するために、この URL を使用する必要があります。この再開可能セッションの URL をコピーして保存し、後続のリクエストで使用できるようにします。
ステップ 3: ファイルをアップロードする
再開可能なセッションでファイルをアップロードするには、2 つの方法があります。
- 単一リクエスト。通常はこの方法が最適です。リクエストが少なく、パフォーマンスが向上するためです。
-
複数のチャンク。 このアプローチでは、データをチャンク化して、複数のリクエストでアップロードを行います。データは
x-goog-upload-chunk-granularityの倍数にチャンクされます。必要に応じて、チャンクされたリクエストを再試行できます。次の場合に使用します。
- 1 つのリクエストで転送されるデータの量を減らす必要があります。個々のリクエストに一定の時間制限がある場合、この操作が必要になることがあります。
- アップロードの進行状況を示すカスタム インジケーターを用意する必要があります。
- データを安全に破棄できるタイミングを知る必要があります。
単一のリクエスト
ファイルを単一リクエストでアップロードするには:
- 再開可能セッションの URL への
POSTリクエストを作成します。 - ファイルのデータをリクエストの本文に追加します。
次の HTTP ヘッダーを追加します。
Content-Length: ファイルのバイト数に設定します。X-Goog-Upload-Command:upload, finalizeに設定します。
リクエストを送信します。
アップロード リクエストが中断された場合、または 5xx レスポンスが返された場合は、中断されたアップロードを再開するの手順に沿って操作してください。
リクエストが成功すると、レスポンスの本文で 200 OK HTTP ステータス コードとアップロード トークンを受け取ります。このアップロード トークンを使用してメディア アイテムを作成します。
複数のチャンク
複数のチャンクでファイルをアップロードするには:
- 再開可能セッションの URL への
POSTリクエストを作成します。 -
チャンクのデータをリクエストの本文に追加します。
アップロードを完了する最後のチャンクを除き、他のチャンクは許容されるチャンクサイズの倍数で作成します。アップロードを効率的に行えるよう、チャンクサイズはできるだけ大きくしてください。
-
次の HTTP ヘッダーを追加します。
Content-Length: チャンクのバイト数に設定します。X-Goog-Upload-Command:uploadに設定します。最後のチャンクでは、upload, finalizeに設定します。X-Goog-Upload-Offset: バイトを書き込むオフセットに設定します。バイトは順番にアップロードする必要があります。最初のオフセットは0です。
- リクエストを送信します。
アップロード リクエストが中断された場合、または
5xxレスポンスが返された場合は、中断されたアップロードを再開するの手順に沿って操作してください。 - ファイル内の残りのチャンクごとに、上記の手順を繰り返します。
リクエストが成功すると、レスポンスの本文で 200 OK HTTP ステータス コードとアップロード トークンを受け取ります。このアップロード トークンを使用してメディア アイテムを作成します。
例
単一のリクエスト
次の例は、1 回のリクエストで 3,039,417 バイトの JPEG ファイルをアップロードする再開可能リクエストを示しています。
POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: image/jpeg X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: 3039417 [no body]
レスポンスには、アップロード URL と予想されるチャンクサイズが含まれます。
HTTP/1.1 200 OK X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable X-Goog-Upload-Chunk-Granularity: 262144
最後のアップロード リクエスト:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 3039417 X-Goog-Upload-Command: upload, finalize X-Goog-Upload-Offset: 0 [BYTES 0-4199999]
複数のチャンク
次の例は、再開可能セッションの URL と前の手順で取得したチャンクサイズの粒度を使用して、3,039,417 バイトの JPEG ファイルを複数のチャンクでアップロードする再開可能リクエストを示しています。この例では、アップロード セッションが初期化されたときにヘッダー フィールド x-goog-upload-chunk-granularity で返された 262,144 バイトのチャンクサイズを使用します。各アップロードには、262,144 の倍数のバイトが含まれることに注意してください。
前のステップで説明したように、アップロード URL とチャンクサイズを受け取るようにアップロード セッションを初期化します。
POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: image/jpeg X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: 3039417 [no body]
レスポンスには、アップロード URL と予想されるチャンクサイズが含まれます。
HTTP/1.1 200 OK X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable X-Goog-Upload-Chunk-Granularity: 262144
最初のチャンク:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 1048576 X-Goog-Upload-Command: upload X-Goog-Upload-Offset: 0 [BYTES 0-1048575]
2 番目のチャンク:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 1048576 X-Goog-Upload-Command: upload X-Goog-Upload-Offset: 1048576 [BYTES 1048576-2097151]
最後のチャンク:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 942265 X-Goog-Upload-Command: upload, finalize X-Goog-Upload-Offset: 2097152 [BYTES 2097152-4200000]
中断されたアップロードの再開
アップロード リクエストが中断された場合、または 200 以外の HTTP ステータス コードを受け取った場合は、サーバーにクエリして、アップロードがどの程度成功したかを確認します。
以下は、再開可能セッションの URL に対する POST リクエストです。X-Goog-Upload-Command を query に設定する必要があります。
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: query
サーバーからのレスポンスには、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 でない場合は、アップロードがすでに終了していることを示します。