На этой странице описано, как отправить запрос на возобновляемую загрузку в 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: Загрузка файла
Есть два способа загрузить файл с возобновляемой сессией:
- В одном запросе. Этот подход обычно является лучшим, поскольку требует меньшего количества запросов и, следовательно, обеспечивает более высокую производительность.
В нескольких кусках. При таком подходе загрузка осуществляется несколькими запросами путем фрагментирования данных. Данные разбиты на фрагменты, кратные
x-goog-upload-chunk-granularity. При необходимости фрагментированные запросы можно повторить.Используйте этот подход, если:
- Вам необходимо уменьшить объем данных, передаваемых в любом отдельном запросе. Это может потребоваться, если для отдельных запросов установлен фиксированный срок.
- Вам необходимо предоставить индивидуальный индикатор, показывающий ход загрузки.
- Вам необходимо знать, когда безопасно удалять данные.
Единый запрос
Чтобы загрузить файл одним запросом:
- Создайте запрос
POSTк URL-адресу возобновляемого сеанса. - Добавьте данные файла в тело запроса.
Добавьте следующие HTTP-заголовки:
-
Content-Length: устанавливает количество байтов в файле. -
X-Goog-Upload-Command: установитьupload, finalize.
-
Отправьте запрос.
Если запрос на загрузку прерван или вы получили ответ 5xx , выполните процедуру, описанную в разделе «Возобновление прерванной загрузки» .
Если запрос успешен, вы получите код состояния HTTP 200 OK и токен загрузки в теле ответа. Создайте элемент мультимедиа, используя этот токен загрузки.
Несколько кусков
Чтобы загрузить файл несколькими частями:
- Создайте запрос
POSTк URL-адресу возобновляемого сеанса. Добавьте данные чанка в тело запроса.
За исключением последнего фрагмента, завершающего загрузку, создайте остальные фрагменты, кратные принятому размеру фрагментов. Сохраняйте размер фрагмента как можно большим, чтобы загрузка была эффективной.
Добавьте следующие HTTP-заголовки:
-
Content-Length: установлено количество байтов в фрагменте. -
X-Goog-Upload-Command: Установитьupload. Для последнего фрагмента, готового кupload, finalize. -
X-Goog-Upload-Offset: устанавливает смещение, с которым должны записываться байты. Обратите внимание, что байты необходимо загружать последовательно. Первое смещение равно0.
-
- Отправьте запрос.
Если запрос на загрузку прерван или вы получили ответ
5xx, выполните процедуру, описанную в разделе «Возобновление прерванной загрузки» . - Повторите эти шаги для каждого оставшегося фрагмента файла.
Если запрос успешен, вы получите код состояния 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 , это означает, что загрузка уже прекращена.