Возобновляемые загрузки

На этой странице описано, как отправить запрос на возобновляемую загрузку в API библиотеки Google Фото через протокол REST. Этот протокол позволяет возобновить операцию загрузки после того, как сбой связи прерывает поток данных.

Если вы разработчик, использующий клиентские библиотеки, обратите внимание, что некоторые клиентские библиотеки предоставляют встроенную поддержку возобновляемых загрузок.

Используйте опцию возобновляемой загрузки, если:

  • Вы загружаете большие файлы.
  • Высока вероятность прерывания сети или какого-либо другого сбоя передачи (например, если вы загружаете файл из мобильного приложения).

Возобновляемые загрузки также могут снизить использование полосы пропускания в случае сбоя сети, поскольку вам не нужно перезапускать загрузку больших файлов с самого начала.

Шаг 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 возвращает код состояния HTTP 200 OK , включая следующий заголовок.

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: Загрузка файла

Есть два способа загрузить файл с возобновляемой сессией:

  1. В одном запросе. Этот подход обычно является лучшим, поскольку он требует меньшего количества запросов и, следовательно, обеспечивает более высокую производительность.

  2. В нескольких кусках. При таком подходе загрузка осуществляется несколькими запросами путем фрагментации данных. Данные разбиваются на фрагменты, кратные x-goog-upload-chunk-granularity . При необходимости фрагментированные запросы можно повторить.

    Используйте этот подход, если:

    • Вам необходимо уменьшить объем данных, передаваемых в любом отдельном запросе. Это может потребоваться, если для отдельных запросов установлен фиксированный срок.
    • Вам необходимо предоставить индивидуальный индикатор, показывающий ход загрузки.
    • Вам необходимо знать, когда безопасно удалять данные.

Единый запрос

Чтобы загрузить файл одним запросом:

  1. Создайте запрос POST к URL-адресу возобновляемого сеанса.
  2. Добавьте данные файла в тело запроса.

  3. Добавьте следующие HTTP-заголовки:

    • Content-Length : устанавливает количество байтов в файле.
    • X-Goog-Upload-Command : установить upload, finalize .

  4. Отправьте запрос.

Если запрос на загрузку прерван или вы получили ответ 5xx , выполните процедуру, описанную в разделе «Возобновление прерванной загрузки» .

Если запрос успешен, вы получите код состояния HTTP 200 OK и токен загрузки в теле ответа. Создайте элемент мультимедиа, используя этот токен загрузки.

Несколько кусков

Чтобы загрузить файл несколькими частями:

  1. Создайте запрос POST к URL-адресу возобновляемого сеанса.

  2. Добавьте данные чанка в тело запроса.

    За исключением последнего фрагмента, завершающего загрузку, создайте остальные фрагменты, кратные принятому размеру фрагментов. Сохраняйте размер фрагмента как можно большим, чтобы загрузка была эффективной.

  3. Добавьте следующие HTTP-заголовки:

    • Content-Length : установлено количество байтов в фрагменте.
    • X-Goog-Upload-Command : Установить upload . Для последнего фрагмента, готового к upload, finalize .
    • X-Goog-Upload-Offset : устанавливает смещение, с которым должны записываться байты. Обратите внимание, что байты необходимо загружать последовательно. Первое смещение равно 0 .
  4. Отправьте запрос.

    Если запрос на загрузку прерван или вы получили ответ 5xx , выполните процедуру, описанную в разделе «Возобновление прерванной загрузки» .

  5. Повторите вышеуказанные шаги для каждого оставшегося фрагмента файла.

Если запрос успешен, вы получите код состояния HTTP 200 OK и токен загрузки в теле ответа. Создайте элемент мультимедиа, используя этот токен загрузки.

Пример

Единый запрос

В следующем примере показан возобновляемый запрос на отправку файла JPEG размером 3 039 417 байт в одном запросе.

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]

Несколько кусков

В следующем примере показан возобновляемый запрос на загрузку файла JPEG размером 3 039 417 байт в нескольких фрагментах с использованием URL-адреса возобновляемого сеанса и принятой степени детализации размера фрагмента, полученной на предыдущем шаге. В этом примере используется размер фрагмента размером 262 144 байта, который был возвращен в поле заголовка x-goog-upload-chunk-granularity при инициализации сеанса загрузки. Обратите внимание, что каждая загрузка содержит байты, кратные 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]

Второй кусок:

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]

Возобновление прерванной загрузки

Если запрос на загрузку прерван или вы получили код состояния HTTP, отличный от 200 , запросите сервер, чтобы узнать, какая часть загрузки прошла успешно.

Вот запрос POST к URL-адресу возобновляемого сеанса. 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

Ответ от сервера включает код состояния HTTP 200 OK и текущий размер загрузки.

HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-Size-Received: 100

Затем вы можете возобновить загрузку с этим смещением. Вы должны возобновить работу со смещением, предоставленным сервером, если только вы не отправите комбинированную команду загрузки и завершения; в этом случае вы также можете возобновить со смещением 0.

Если заголовок X-Goog-Upload-Status в HTTP-ответе вашей команды запроса присутствует и значение не active , это означает, что загрузка уже прекращена.