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

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

Пример: запуск возобновляемого сеанса загрузки

В следующем примере показано, как инициировать возобновляемый сеанс для загрузки нового файла. В данном случае файл представляет собой изображение, а общее количество байт в файле равно 4200000. Обратите внимание, что тело запроса пусто; поэтому заголовок 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-адреса возобновляемого сеанса и детализации размера, полученной на предыдущем шаге. В этом примере используется размер фрагмента 2097000 байт, что кратно 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 , то загрузка уже прекращена.