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

На этой странице описано, как отправить запрос на возобновление загрузки в API публикации Street View. Этот протокол позволяет возобновить операцию загрузки после сбоя связи, прервавшего поток данных. Используйте эту опцию, если:

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

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

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

Инициирование сеанса возобновляемой загрузки.

После получения uploadUrl вы можете инициировать сеанс возобновляемой загрузки:

  1. Создайте POST запрос к адресу uploadUrl .

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

    • X-Goog-Upload-Protocol : Установить режим resumable .
    • X-Goog-Upload-Header-Content-Length : Устанавливается в общее количество байтов данных файла, которые будут переданы в последующих запросах.
    • X-Goog-Upload-Header-Content-Type : Установите значение MIME-типа данных файла.
    • X-Goog-Upload-Command : Установить для start .

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

Пример: Инициирование сеанса возобновляемой загрузки.

В следующем примере показано, как инициировать возобновляемую сессию для загрузки нового файла. В данном случае файл представляет собой изображение, и общее количество байтов в файле составляет 4 200 000. Обратите внимание, что тело запроса пустое; поэтому заголовок Content-Length установлен на 0.

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234 HTTP/1.1
Authorization: Bearer [YOUR_AUTH_TOKEN]
Content-Length: 0
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Header-Content-Length: 4200000
X-Goog-Upload-Header-Content-Type: image/jpeg
X-Goog-Upload-Command: start

В разделе «Сохранение URL-адреса возобновляемой сессии» описывается, как обрабатывать ответ на запрос на запуск возобновляемой сессии загрузки.

Сохранение URL-адреса возобновляемой сессии

В ответ на запрос на инициирование возобновляемой сессии загрузки сервер отправит HTTP-код состояния 200 OK , включающий следующий заголовок:

  • X-Goog-Upload-URL : Уникальный URL-адрес, который необходимо использовать для завершения загрузки во всех последующих запросах.

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

Пример: Сохранение URL-адреса возобновляемой сессии.

В следующем примере показан ответ, включающий URL-адрес возобновляемой сессии и требование к точности размера.

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable

Загрузка файла

Существует два способа загрузки файла с возможностью возобновления сессии:

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

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

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

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

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

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

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

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

Несколько фрагментов

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

  1. Создайте POST запрос к URL-адресу возобновляемой сессии.
  2. Добавьте данные фрагмента в тело запроса. Создавайте фрагменты размером, кратным 2 МиБ (мебибайтам), за исключением последнего фрагмента, завершающего загрузку. Старайтесь, чтобы размер фрагмента был как можно больше для обеспечения эффективности загрузки.

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

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

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

  5. Повторите шаги с 1 по 4 для каждого оставшегося фрагмента файла.

Пример: Загрузка файла

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

В следующем примере показан возобновляемый запрос на загрузку всего файла JPEG размером 4 200 000 байт за один запрос с использованием URL-адреса возобновляемой сессии, полученного на предыдущем шаге:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 4200000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

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

Несколько фрагментов

В следующем примере показан возобновляемый запрос на загрузку файла JPEG размером 4 200 000 байт несколькими фрагментами, с использованием URL-адреса возобновляемой сессии и гранулярности размера, полученной на предыдущем шаге. В этом примере используется размер фрагмента 2 097 000 байт, что кратно 2 МиБ (мебибайтам).

Первый фрагмент:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0



[BYTES 0-2096999]

Второй фрагмент:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 2097000



[BYTES 2097000-4193999]

Последний фрагмент:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 6000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 4194000



[BYTES 4194000-4200000]

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

Если запрос на загрузку прерван или вы получили HTTP-код состояния, отличный от 200 , запросите у сервера информацию о том, какая часть загрузки прошла успешно:

  1. Создайте POST запрос к URL-адресу возобновляемой сессии.
  2. Настройте команду X-Goog-Upload-Command на query .
  3. Отправьте запрос.

Сервер ответит кодом состояния 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 , значит, загрузка уже прервана.