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.
Si eres desarrollador y usas bibliotecas cliente, ten en cuenta que algunas bibliotecas cliente brindan compatibilidad nativa con cargas reanudables.
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
Iniciar una sesión de carga reanudable enviando 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 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, porque requiere menos solicitudes y, por lo tanto, tiene un mejor rendimiento.
-
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:
- Debes reducir la cantidad de datos transferidos en cualquier para cada 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 un proyecto.
- 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 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:
- 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. Mantén la para que el tamaño del fragmento sea lo más grande posible para que la carga sea eficiente.
-
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 el bytes deben estar escritos. 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 los pasos anteriores 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.
Crear
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
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
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.