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

На этой странице описано, как отправить запрос на возобновляемую загрузку в 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 , это означает, что загрузка уже прекращена.