Cargas reanudables

En esta página, se describe cómo realizar una solicitud de carga reanudable a la API de la Biblioteca de Google Fotos a través del protocolo REST. Este protocolo te permite reanudar una operación de carga tras una falla de comunicación interrumpe el flujo de datos.

Usa la opción de carga reanudable en los siguientes casos:

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

Las cargas reanudables también pueden reducir el uso de ancho de banda cuando hay una red ya que no es necesario reiniciar las cargas de archivos grandes desde la empezando.

Paso 1: Inicia una sesión de carga

Para iniciar una sesión de carga reanudable, envía una solicitud POST a https://photoslibrary.googleapis.com/v1/uploads. Usa la carga reanudable URL que se muestra en esta solicitud, sube el archivo.

La solicitud POST debe incluir los siguientes encabezados:

Campos de encabezado
Content-Length Se establece en 0, ya que el cuerpo de la solicitud está vacío.
X-Goog-Upload-Command Debes establecerlo en start.
X-Goog-Upload-Content-Type Configurar como el tipo MIME del archivo; por ejemplo, image/jpeg
X-Goog-Upload-Protocol Debes establecerlo en resumable.
X-Goog-Upload-Raw-Size Configurado como la cantidad total de bytes de los datos del archivo que se de almacenamiento y la cantidad de datos transferidos.

Este es un encabezado de solicitud 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

Paso 2: Guarda la URL de la sesión

Si se realiza correctamente, la solicitud POST muestra un código de estado HTTP 200 OK, que incluye lo siguiente: el siguiente encabezado.

X-Goog-Upload-URL: url-to-make-uploads-to
X-Goog-Upload-Chunk-Granularity: chunk-granularity-in-bytes

El campo de encabezado x-goog-upload-chunk-granularity contiene la alineación de bytes y el nivel de detalle de tamaño de todos los fragmentos de datos que envía el cliente. Si la carga es realizar en varios fragmentos, todas las cargas, excepto la última debe hacerse en múltiplos de este valor. Es decir, los bytes de carga del archivo debe alinearse con este valor. En el último bloque, puedes subir el resto bytes.

El campo del encabezado X-Goog-Upload-URL contiene una URL única que se debe usar para lo siguiente: complete la carga con todas las solicitudes restantes. Copiar y guardar la URL de la sesión reanudable, de modo que puedas usarla en solicitudes posteriores.

Paso 3: 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 mejor, porque requiere menos solicitudes y, por lo tanto, tiene un mejor rendimiento.
  2. En varios fragmentos: Con este enfoque, las cargas se realizan en varias solicitudes mediante la fragmentación de los datos. Los datos se fragmentan múltiplos de x-goog-upload-chunk-granularity. Si es necesario, las solicitudes fragmentadas se pueden volver a intentar.

    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 la carga. el progreso de los cambios.
    • 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 .
    • X-Goog-Upload-Command: Configurado como upload, finalize.
  4. Envía la solicitud.

Si se interrumpe la solicitud de carga o recibes un 5xx respuesta, sigue el procedimiento que se describe en Cómo reanudar una carga interrumpida.

Si la solicitud se realiza correctamente, recibirás un estado HTTP 200 OK. y un token de carga en el cuerpo de la respuesta. Crear el elemento multimedia con este token de carga.

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.

    Excepto el último fragmento que completa la carga, crea los demás fragmentos en múltiplos del tamaño aceptado de fragmentos. Mantén la para que el tamaño del fragmento sea lo más grande posible para que la carga sea eficiente.

  3. Agrega los siguientes encabezados HTTP:

    • Content-Length: Se establece en la cantidad de bytes del bloque.
    • X-Goog-Upload-Command: Configurado como upload. En el último fragmento, configúralo como upload, finalize.
    • X-Goog-Upload-Offset: se establece en el desplazamiento en el que el bytes deben estar escritos. Ten en cuenta que los bytes se deben subir de forma serial. El primer desplazamiento es 0.
  4. Envía la solicitud.

    Si se interrumpe la solicitud de carga o recibes un 5xx respuesta, sigue el procedimiento que se describe en Cómo reanudar una carga interrumpida.

  5. Repite estos pasos para cada fragmento restante del archivo.

Si la solicitud se realiza correctamente, recibirás un estado HTTP 200 OK. y un token de carga en el cuerpo de la respuesta. Crea el elemento multimedia con este token de carga.

Ejemplo

Solicitud única

En el siguiente ejemplo, se muestra una solicitud reanudable para subir un archivo JPEG de 3,039,417 bytes en una sola solicitud.

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]

La respuesta contiene la URL de carga y el tamaño de fragmento esperado:

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

Esta es la solicitud de carga final:

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]

Varios fragmentos

En el siguiente ejemplo, se muestra una solicitud reanudable para subir un Archivo JPEG de 3,039,417 bytes en varios fragmentos, con la sesión reanudable URL y el nivel de detalle del tamaño de fragmento aceptado que obtuviste en el paso anterior. En este ejemplo, se usa un tamaño de fragmento de 262,144 bytes que se devolvió en campo de encabezado, x-goog-upload-chunk-granularity, cuando el valor de carga se inicializó. Ten en cuenta que cada carga contiene bytes que están en múltiplos de 262.144.

Inicializa la sesión de carga para recibir la URL de carga y el tamaño del fragmento. como se describe en el paso anterior:

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]

La respuesta contiene la URL de carga y el tamaño de fragmento esperado:

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

Primer fragmento:

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]

Segundo fragmento:

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]

Último fragmento:

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]

Reanuda una carga interrumpida

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

Esta es una solicitud POST a la URL de la sesión reanudable. X-Goog-Upload-Command se debe establecer en 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

La respuesta del servidor incluye 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 ajuste. Debes reanudar en el desplazamiento que proporciona el servidor, a menos que envíes un comando de carga y finalización combinados, en cuyo caso también puedes reanudar con el desplazamiento 0.

Si el encabezado X-Goog-Upload-Status en la respuesta HTTP del comando de consulta está presente y el valor no es active, lo que indica que la carga tiene ya se cancelaron.