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 después de que una falla de comunicación interrumpe el flujo de datos. Usa esta opción en los siguientes casos:

  • Subes archivos grandes.
  • La probabilidad de una interrupción de red o algún otro error 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 de ancho de banda cuando hay una falla de red, ya que no es necesario 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 de 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 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.

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

Para la solicitud que se envía para iniciar una sesión de carga reanudable, el servidor responderá con un código de estado HTTP 200 OK, incluido el siguiente encabezado:

  • X-Goog-Upload-URL: Es 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 la sesión reanudable para que puedas usarla 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 de 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: Este enfoque suele ser el más conveniente, ya que requiere menos solicitudes y, por lo tanto, tiene un mejor rendimiento.
  2. En varios fragmentos: Usa este enfoque en los siguientes casos:
    • Si debes reducir la cantidad de datos transferidos en una solicitud. Es posible que debas hacer esto cuando haya un límite de tiempo fijo para 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 en 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 del fragmento debe ser lo más grande posible para que la carga sea eficaz.

  3. Agrega los siguientes encabezados HTTP:

    • Content-Length: Se establece en la cantidad de bytes del fragmento.
    • X-Goog-Upload-Command: Configurado como upload. Para el último fragmento, configúralo como 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 deben subirse en serie.

  4. Envía la solicitud. Si la solicitud de carga se interrumpe 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: Sube 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, con la URL de la sesión reanudable que se obtuvo 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, con 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 2097000 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 saber qué parte 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 en este desplazamiento. Debes reanudar con 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 la carga ya se finalizó.