再開可能なアップロード

このページでは、Google Photos Library API に再開可能なアップロード リクエストを行う方法について説明します。 通信できます。このプロトコルを使用すると、アップロード操作を再開できます。 データフローが中断されます

次の場合は、再開可能なアップロード オプションを使用します。

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

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

ステップ 1: アップロード セッションを開始する

POST リクエストを次の場所に送信して、再開可能なアップロードのセッションを開始する https://photoslibrary.googleapis.com/v1/uploads。再開可能なアップロードの使用 このリクエストで返された 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 を使用して、 残りのすべてのリクエストでアップロードが完了します。これをコピーして保存してください 後続のリクエストに使用できます。

ステップ 3: ファイルをアップロードする

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

  1. 単一のリクエスト内。通常はこの方法が最適です。 リクエストが少ないため、パフォーマンスが向上します。
  2. 複数のチャンク。 この方法では、データをチャンクにすることで、複数のリクエストでアップロードが行われます。データは、複数の x-goog-upload-chunk-granularity の倍数です。必要に応じて チャンクされたリクエストを再試行できます。

    次の場合に使用します。

    • 1 つのリクエストで転送するデータの量を減らす必要がある。期限が固定されている場合に、この操作が必要になることがあります。 できます。
    • アップロードを示すカスタム インジケーターを提供する必要があります できます。
    • データを安全に破棄できるタイミングを把握する必要があります。

単一のリクエスト

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

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

    • Content-Length: ファイルのバイト数に設定します。 表示されます。
    • X-Goog-Upload-Command: upload, finalize に設定します。
  4. リクエストを送信します。

アップロード リクエストが中断された場合、または 5xx が表示された場合 をご覧ください。

リクエストが成功すると、200 OK HTTP ステータスが返されます。 レスポンスの本文でアップロード トークンを渡します。 作成 このアップロード トークンを使用してメディア アイテムを取得します。

複数のチャンク

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

  1. 再開可能セッションの URL への POST リクエストを作成します。
  2. チャンクのデータをリクエストの本文に追加します。

    アップロードを完了する最後のチャンクを除き、 他のチャンクも許容されるサイズの倍数で分割します。現在の アップロードが効率的に行われるように、チャンクサイズを大きくします。

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

    • Content-Length: ファイルのバイト数に設定します。 分割されます。
    • X-Goog-Upload-Command: upload に設定します。最後のチャンクでは、upload, finalize に設定します。
    • X-Goog-Upload-Offset: 書き込まれるはずです。バイトは順番にアップロードする必要がある点に注意してください。最初のオフセットは 0 です。
  4. リクエストを送信します。

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

  5. ファイル内の残りのチャンクごとに、上記の手順を繰り返します。

リクエストが成功すると、200 OK HTTP ステータスが返されます。 レスポンスの本文でアップロード トークンを渡します。 作成 このアップロード トークンを使用してメディア アイテムを取得します。

単一のリクエスト

次の例は、Cloud Storage バケットをアップロードする再開可能なリクエストを示しています。 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 ファイルを複数のチャンクでアップロードする再開可能なリクエストを示しています。この例では、262,144 バイトのチャンクサイズを使用しています。 ヘッダー フィールド x-goog-upload-chunk-granularity が、 アップロード セッションが初期化されました。各アップロードには、365 バイトを超える 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 ではない場合、アップロードが終了したことを示します。 すでに解除されています