Realiza una carga reanudable

En esta página, se describe cómo realizar una solicitud de carga reanudable en la API de Street View Publish. Este protocolo te permite reanudar una operación de carga cuando una falla de comunicación interrumpe el flujo de datos. Usa esta opción en los siguientes casos:

  • Estás subiendo archivos grandes.
  • La probabilidad de que se produzca una interrupción en la red o de alguna otra falla de transmisión es alta (por ejemplo, si subes un archivo desde una app para dispositivos móviles).

Las cargas reanudables también pueden reducir el uso del ancho de banda cuando hay una falla de red, ya que no necesitas reiniciar las cargas de archivos grandes desde el principio.

Si envías archivos pequeños a través de una conexión de red confiable, puedes usar una carga simple.

Inicia una sesión de carga reanudable

Después de obtener un uploadUrl, puedes iniciar una sesión de carga reanudable:

  1. Crea una solicitud POST a uploadUrl.

  2. Agrega los siguientes encabezados HTTP:

    • X-Goog-Upload-Protocol: Configurado como resumable.
    • X-Goog-Upload-Header-Content-Length: Se establece como la cantidad total de bytes de los datos del archivo, que se transferirán en solicitudes posteriores.
    • X-Goog-Upload-Header-Content-Type: Se establece en el tipo de MIME de los datos del archivo.
    • X-Goog-Upload-Command: Configurado como start.

  3. Envía la solicitud.

Ejemplo: Cómo iniciar una sesión de carga reanudable

En el siguiente ejemplo, se muestra cómo iniciar una sesión reanudable para subir un archivo nuevo. En este caso, el archivo es una imagen y la cantidad total de bytes en el archivo es 4,200,000. Ten en cuenta que el cuerpo de la solicitud está vacío; por lo tanto, el encabezado Content-Length se establece en 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

En Cómo guardar la URL de la sesión reanudable, se describe cómo controlar la respuesta de la solicitud para iniciar la sesión de carga reanudable.

Guarda la URL de la sesión reanudable

A la solicitud enviada para iniciar una sesión de carga reanudable, el servidor responderá con un código de estado HTTP 200 OK, que incluye el siguiente encabezado:

  • X-Goog-Upload-URL: Una URL única que se debe usar para completar la carga a través de todas las solicitudes restantes.

Copia y guarda la URL de resión reanudable para poder utilizarla en solicitudes posteriores.

Ejemplo: Cómo guardar la URL de la sesión reanudable

En el siguiente ejemplo, se muestra una respuesta que incluye una URL de sesión reanudable y un requisito de nivel de detalle del tamaño.

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

Sube el archivo

Existen dos formas de subir un archivo con una sesión reanudable:

  1. En una sola solicitud: Por lo general, este enfoque es el mejor, ya que requiere menos solicitudes y, por lo tanto, tiene un mejor rendimiento.
  2. En varios fragmentos: Usa este enfoque en los siguientes casos:
    • Debes reducir la cantidad de datos transferidos en una misma solicitud. Es posible que debas hacerlo cuando haya un límite de tiempo fijo para las solicitudes individuales.
    • Debes proporcionar un indicador personalizado que muestre el progreso de la carga.
    • Debes saber cuándo es seguro descartar datos.

Solicitud única

Para subir el archivo en una sola solicitud, sigue estos pasos:

  1. Crea una solicitud POST a la URL de la sesión reanudable.
  2. Agrega los datos del archivo al cuerpo de la solicitud.

  3. Agrega los siguientes encabezados HTTP:

    • Content-Length: Se establece como la cantidad de bytes del archivo.
    • X-Goog-Upload-Command: Configurado como upload, finalize.

  4. Envía la solicitud.

Si se interrumpe la solicitud de carga o recibes una respuesta 5xx, sigue el procedimiento que se describe en Reanuda una carga interrumpida.

Varios fragmentos

Para subir el archivo en varios fragmentos, sigue estos pasos:

  1. Crea una solicitud POST a la URL de la sesión reanudable.
  2. Agrega los datos del fragmento al cuerpo de la solicitud. Crea fragmentos en múltiplos de 2 MiB (mebibytes), excepto el último fragmento que completa la carga. El tamaño de los fragmentos debe ser lo más grande posible para que la carga sea eficaz.

  3. Agrega los siguientes encabezados HTTP:

    • Content-Length: Se establece como la cantidad de bytes del fragmento.
    • X-Goog-Upload-Command: Configurado como upload. Para el último fragmento, configúralo en upload, finalize.
    • X-Goog-Upload-Offset: Se establece en el desplazamiento en el que se deben escribir los bytes. Ten en cuenta que los bytes se deben subir en serie.

  4. Envía la solicitud. Si se interrumpe la solicitud de carga o recibes una respuesta 5xx, sigue el procedimiento que se describe en Reanuda una carga interrumpida.

  5. Repite los pasos del 1 al 4 para cada fragmento restante del archivo.

Ejemplo: Cómo subir el archivo

Solicitud única

En el siguiente ejemplo, se muestra una solicitud reanudable para subir un archivo JPEG completo de 4,200,000 bytes en una sola solicitud, mediante la URL de la sesión reanudable que obtuviste en el paso anterior:

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]

Si la solicitud se realiza correctamente, recibirás un código de estado HTTP 200 OK.

Varios fragmentos

En el siguiente ejemplo, se muestra una solicitud reanudable para subir un archivo JPEG de 4,200,000 bytes en varios fragmentos, mediante la URL de la sesión reanudable y el nivel de detalle de tamaño obtenido en el paso anterior. En este ejemplo, se usa un tamaño de fragmento de 2097,000 bytes, que es un múltiplo de 2 MiB (mebibytes).

Primer fragmento: 

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]

Segundo fragmento: 

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]

Último fragmento: 

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]

Reanuda una carga interrumpida

Si se interrumpe la solicitud de carga o si recibes un código de estado HTTP que no es 200, consulta el servidor para averiguar qué porcentaje de la carga se realizó correctamente:

  1. Crea una solicitud POST a la URL de la sesión reanudable.
  2. Establece la X-Goog-Upload-Command en query.
  3. Envía la solicitud.

El servidor responderá con un código de estado HTTP 200 OK y el tamaño actual de la carga:

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

Luego, puedes reanudar la carga con este desplazamiento. Debes reanudar en el desplazamiento proporcionado por el servidor, a menos que envíes un comando combinado de carga y finalización, en cuyo caso también puedes reanudar con el desplazamiento 0.

Si el encabezado X-Goog-Upload-Status en la respuesta HTTP de tu comando de consulta está presente y el valor no es active, significa que ya se canceló la carga.