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 cuando una falla de comunicación interrumpe el flujo de datos.
Usa la opción de carga reanudable 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.
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 |
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 |
Se establece en 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, 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 de tamaño para 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:
- En una sola solicitud: Este enfoque suele ser el mejor, ya que requiere menos solicitudes y, por lo tanto, tiene un mejor rendimiento.
-
En varios fragmentos: En este enfoque, las cargas se realizan en varias solicitudes dividiendo los datos en fragmentos. Los datos se dividen en múltiplos de
x-goog-upload-chunk-granularity. Si es necesario, se pueden volver a intentar las solicitudes divididas en 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.
- Si 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 en la cantidad de bytes del .X-Goog-Upload-Command: Configurado comoupload, finalize.
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 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 y 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 eficaz.
-
Agrega los siguientes encabezados HTTP:
Content-Length: Se establece en la cantidad de bytes del bloque.X-Goog-Upload-Command: Configurado comoupload. En 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 se interrumpe la solicitud de carga o recibes un
5xxrespuesta, sigue el procedimiento que se describe en Cómo reanudar una carga interrumpida. - Repite estos pasos 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 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 son 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 código de estado HTTP que no es 200, consulta el servidor para saber qué parte 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 combinado, en cuyo caso también puedes reanudar en 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ó.