En esta página, se describe cómo realizar una solicitud de carga reanudable a la API de la Biblioteca de Google Fotos con el protocolo REST. Con este protocolo, puedes reanudar una operación de carga después de que una falla de comunicación interrumpa el flujo de datos.
Si eres desarrollador y usas bibliotecas cliente, ten en cuenta que algunas de ellas proporcionan compatibilidad nativa con las cargas reanudables.
Usa la opción de carga reanudable 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 tienes que reiniciar cargas de archivos grandes desde el principio.
Paso 1: Cómo iniciar una sesión de carga
Envía una solicitud POST a https://photoslibrary.googleapis.com/v1/uploads para iniciar una sesión de carga reanudable. Con la URL de carga reanudable 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 |
Establece el tipo de MIME del archivo, por ejemplo, image/jpeg. |
X-Goog-Upload-Protocol |
Debes establecerlo en resumable. |
X-Goog-Upload-Raw-Size |
Se establece como la cantidad total de bytes de los datos del archivo que se transferirán. |
A continuación, se muestra un encabezado de la 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 ejecuta correctamente, la solicitud POST muestra un código de estado HTTP 200 OK, incluido 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 del tamaño de todos los fragmentos de datos que envía el cliente. Si la carga se realiza en varios fragmentos, todas las cargas, excepto la última, se deben realizar en múltiplos de este valor. Es decir, los bytes de carga del archivo deben alinearse con este valor. En el último fragmento, puedes subir los bytes restantes.
El campo de encabezado X-Goog-Upload-URL contiene una URL única que se debe usar para completar la carga con todas las solicitudes restantes. Copia y guarda esta URL de sesión reanudable para que puedas usarla en solicitudes posteriores.
Paso 3: Sube el archivo
Existen dos formas de subir un archivo con una sesión reanudable:
- En una sola solicitud: Este enfoque suele ser el mejor porque requiere menos solicitudes y, por lo tanto, tiene un mejor rendimiento.
-
En varios fragmentos: En este enfoque, las cargas se realizan en varias solicitudes fragmentando los datos. Los datos se fragmentan en múltiplos de
x-goog-upload-chunk-granularity. Si es necesario, puedes volver a intentar las solicitudes fragmentadas.Usa este enfoque en los siguientes casos:
- Debes reducir la cantidad de datos transferidos en una sola 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:
- Crea una solicitud
POSTa la URL de la sesión reanudable. - Agrega los datos del archivo al cuerpo de la solicitud.
Agrega los siguientes encabezados HTTP:
Content-Length: Se establece como la cantidad de bytes del archivo.X-Goog-Upload-Command: Configurado comoupload, finalize.
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.
Si la solicitud se realiza correctamente, recibirás un código de estado HTTP 200 OK y un token de carga en el cuerpo de la respuesta.
Crea el elemento multimedia con este token de carga.
Varios fragmentos
Para subir el archivo en varios fragmentos, sigue estos pasos:
- Crea una solicitud
POSTa la URL de la sesión reanudable. -
Agrega los datos del fragmento al cuerpo de la solicitud.
Excepto por el último fragmento que completa la carga, crea los otros fragmentos en múltiplos del tamaño aceptado de los fragmentos. El tamaño del fragmento debe ser lo más grande posible para que la carga sea eficiente.
-
Agrega los siguientes encabezados HTTP:
Content-Length: Se establece como la cantidad de bytes en el fragmento.X-Goog-Upload-Command: Configurado comoupload. Para el último fragmento, configúralo comoupload, 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. El primer desplazamiento es0.
- 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. - Repite los pasos anteriores para cada fragmento restante del archivo.
Si la solicitud se realiza correctamente, recibirás un código de 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
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 URL de la sesión reanudable y el nivel de detalle del tamaño de fragmento aceptado que se obtuvo en el paso anterior.
En este ejemplo, se usa un tamaño de fragmento de 262,144 bytes que se mostró en el campo del encabezado, x-goog-upload-chunk-granularity, cuando se inicializó la sesión de carga. Ten en cuenta que cada carga contiene bytes que son múltiplos de 262,144.
Inicializa la sesión de carga para recibir la URL de carga y el tamaño de 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 bloque:
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 bloque:
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 la solicitud de carga se interrumpe o si recibes un código de estado HTTP que no sea 200, consulta el 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 debe configurarse como 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 proporcionado por el servidor, a menos que envíes un comando combinado de carga y finalización, en cuyo caso también puedes reanudar en 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, significa que la carga ya finalizó.