このページでは、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]
複数のチャンク
次の例は、Cloud Storage バケットをアップロードする再開可能なリクエストを示しています。
複数のチャンク形式の 3,039,417 バイトの JPEG ファイル（再開可能セッションを使用）
URL と、前のステップで取得した受け入れ可能なチャンクサイズの粒度。
この例では、アップロード セッションの初期化時にヘッダー フィールド x-goog-upload-chunk-granularity で返された 262,144 バイトのチャンクサイズを使用します。各アップロードには、300 バイト以上の
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
このオフセットでアップロードを再開できます。再開する場合は、サーバーから提供されたオフセットで行う必要があります。ただし、upload コマンドと finalize コマンドを組み合わせて送信する場合は、オフセットを 0 で再開することもできます。
クエリコマンドの HTTP レスポンスに X-Goog-Upload-Status ヘッダーが存在し、値が active でない場合は、アップロードがすでに終了していることを示しています。