Realiza cargas reanudables

Ir a los conceptos

En esta página, se describe cómo realizar una solicitud de carga reanudable en las API de JSON y XML de Cloud Storage. Este protocolo te permite reanudar una operación de carga luego de que una falla de comunicación haya interrumpido el flujo de datos.

Inicia una sesión de carga reanudable

Para iniciar una sesión de carga reanudable, haz lo siguiente:

API de JSON

Obtén un token de acceso de autorización de OAuth 2.0 Playground. Configura Playground para usar tus credenciales de OAuth.
De manera opcional, crea un archivo .json que contenga los metadatos que deseas configurar en el objeto que deseas subir.
Usa cURL para llamar a la API de JSON con una solicitud de objeto POST:
```
curl -i -X POST --data-binary @METADATA_LOCATION \
    -H "Authorization: Bearer OAUTH2_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Content-Length: INITIAL_REQUEST_LENGTH" \
    "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o?uploadType=resumable&name=OBJECT_NAME"
```
Donde:
- METADATA_LOCATION es la ruta de acceso local al archivo JSON que contiene los metadatos opcionales que especificaste en el paso anterior. Si no incluyes un archivo de metadatos, excluye esto, junto con --data-binary @ y el encabezado Content-Type.
- OAUTH2_TOKEN es el token de acceso que generaste en el paso 1.
- INITIAL_REQUEST_LENGTH es la cantidad de bytes en el cuerpo de esta solicitud inicial, por ejemplo, 79. No es necesario si usas la codificación de transferencia fragmentada.
- BUCKET_NAME es el nombre del depósito al que subes el objeto. Por ejemplo, my-bucket.
- OBJECT_NAME es el nombre nuevo que deseas dar a tu objeto. Por ejemplo, pets/dog.png. Esto no es necesario si incluiste un name en el archivo de metadatos del objeto en el paso 2.
Si habilitaste el uso compartido de recursos entre dominios, también debes incluir un encabezado Origin en esta solicitud de carga y en las posteriores.

Los encabezados opcionales que puedes agregar a la solicitud incluyen X-Upload-Content-Type y X-Upload-Content-Length.

Si la solicitud se completa de forma correcta, la respuesta incluye un código de estado 200.
Guarda el URI de la sesión reanudable que se proporcionó en el encabezado Location de la respuesta a tu solicitud de objeto POST.

Este URI se usa en las solicitudes posteriores para subir los datos del objeto.

Precaución: Ten cuidado cuando compartas el URI de la sesión reanudable, ya que cualquier persona puede usarlo para subir datos al depósito de destino sin ninguna autenticación adicional.

API de XML

Obtén un token de acceso de autorización de OAuth 2.0 Playground. Configura Playground para usar tus credenciales de OAuth.
Usa cURL para llamar a la API de XML con una solicitud de objeto POST que tenga un cuerpo vacío:
```
curl -i -X POST -H "Authorization: Bearer OAUTH2_TOKEN" \
    -H "Content-Length: 0" \
    -H "Content-Type: OBJECT_CONTENT_TYPE" \
    -H "x-goog-resumable: start" \
    "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"
```
Donde:
- OAUTH2_TOKEN es el token de acceso que generaste en el paso 1.
- OBJECT_CONTENT_TYPE es el tipo de contenido del objeto. Por ejemplo, image/png. Si no especificas un tipo de contenido, el sistema de Cloud Storage establece los metadatos Content-Type para que el objeto sea application/octet-stream.
- BUCKET_NAME es el nombre del depósito al que subes el objeto. Por ejemplo, my-bucket.
- OBJECT_NAME es el nombre nuevo que deseas darle al objeto. Por ejemplo, pets/dog.png.
Si habilitaste el uso compartido de recursos entre dominios, también debes incluir un encabezado Origin en esta solicitud de carga y en las posteriores.

Si la solicitud se completa de forma correcta, la respuesta incluye un mensaje de estado 201.
Guarda el URI de la sesión reanudable que se proporcionó en el encabezado Location de la respuesta a tu solicitud de objeto POST.

Este URI se usa en las solicitudes posteriores para subir los datos del objeto.

Precaución: Ten cuidado cuando compartas el URI de la sesión reanudable, ya que cualquier persona puede usarlo para subir datos al depósito de destino sin ninguna autenticación adicional.

Sube el archivo

Una vez que inicias una carga reanudable, hay dos formas de subir los datos del objeto:

En una sola solicitud: este método suele ser el mejor, ya que requiere menos solicitudes y, por lo tanto, tiene un mejor rendimiento.
En varios fragmentos: usa este método si necesitas reducir la cantidad de datos transferidos en una sola solicitud, como cuando hay un límite de tiempo fijo para solicitudes individuales, o si no sabes cuál es el tamaño total de la carga en el momento en que se inicia.

Carga en una sola solicitud

Para subir el archivo en una sola solicitud, sigue estos pasos:

API de JSON

Usa cURL para llamar a la API de JSON con una solicitud de objeto PUT:
```
curl -i -X PUT --data-binary @OBJECT_LOCATION \
    -H "Content-Length: OBJECT_SIZE" \
    "SESSION_URI"
```
Donde:
- OBJECT_LOCATION es la ruta de acceso local a tu objeto. Por ejemplo, Desktop/dog.png.
- OBJECT_SIZE es la cantidad de bytes en el objeto. Por ejemplo, 20000000.
- SESSION_URI es el valor que se mostró en el encabezado Location cuando iniciaste la carga reanudable.

API de XML

Usa cURL para llamar a la API de XML con una solicitud de objeto PUT:
```
curl -i -X PUT --data-binary @OBJECT_LOCATION \
    -H "Content-Length: OBJECT_SIZE" \
    "SESSION_URI"
```
Donde:
- OBJECT_LOCATION es la ruta de acceso local a tu objeto. Por ejemplo, Desktop/dog.png.
- OBJECT_SIZE es la cantidad de bytes en el objeto. Por ejemplo, 20000000.
- SESSION_URI es el valor que se mostró en el encabezado Location cuando iniciaste la carga reanudable.

Si la carga se completa en su totalidad, recibirás una respuesta 200 OK o 201 Created, junto con todos los metadatos asociados con el recurso.

Si la solicitud de carga se interrumpe o si recibes una respuesta 5xx, sigue el procedimiento que se describe en Reanuda una carga interrumpida.

Carga en varios fragmentos

Para subir el archivo en varios fragmentos, sigue estos pasos:

API de JSON

Crea un fragmento de datos a partir del archivo que deseas subir.

El tamaño del fragmento debe ser un múltiplo de 256 KiB (256 x 1024 bytes), a menos que sea el último fragmento que complete la carga. Por lo general, los tamaños de fragmentos más grandes hacen que las cargas sean más eficientes. Recomendamos usar 8 MiB para el tamaño del fragmento.
Usa cURL para llamar a la API de JSON con una solicitud de objeto PUT:
```
curl -i -X PUT --data-binary @CHUNK_LOCATION \
    -H "Content-Length: CHUNK_SIZE" \
    -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \
    "SESSION_URI"
```
Donde:
- CHUNK_LOCATION es la ruta de acceso local al fragmento que subes en este momento.
- CHUNK_SIZE es la cantidad de bytes que subes en la solicitud actual. Por ejemplo, 524288.
- CHUNK_FIRST_BYTE es el byte inicial en el objeto completo que contiene el fragmento que deseas subir.
- CHUNK_LAST_BYTE es el byte final del objeto completo que contiene el fragmento que deseas subir.
- TOTAL_OBJECT_SIZE es el tamaño total del objeto que deseas subir.
- SESSION_URI es el valor que se mostró en el encabezado Location cuando iniciaste la carga reanudable.
Un ejemplo de Content-Range es Content-Range: bytes 0-524287/2000000. Consulta Content-Range para obtener más información sobre este encabezado.

Si la solicitud se completa de forma correcta, el servidor responde con 308 Resume Incomplete. La respuesta contiene un encabezado Range. Usa el valor superior de este encabezado para determinar dónde comenzar el siguiente fragmento. No debes suponer que el servidor recibió todos los bytes que se enviaron en la solicitud.
Repite los pasos anteriores para cada fragmento restante de los datos que deseas subir.

API de XML

Crea un fragmento de datos a partir del archivo que deseas subir.

El tamaño del fragmento debe ser un múltiplo de 256 KiB (256 x 1024 bytes), a menos que sea el último fragmento que complete la carga. Por lo general, los tamaños de fragmentos más grandes hacen que las cargas sean más eficientes. Recomendamos usar 8 MiB para el tamaño del fragmento.
Usa cURL para llamar a la API de XML con una solicitud de objeto PUT:
```
curl -i -X PUT --data-binary @CHUNK_LOCATION \
    -H "Content-Length: CHUNK_SIZE" \
    -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \
    "SESSION_URI"
```
Donde:
- CHUNK_LOCATION es la ruta de acceso local al fragmento que subes en este momento.
- CHUNK_SIZE es la cantidad de bytes que subes en la solicitud actual. Por ejemplo, 524288.
- CHUNK_FIRST_BYTE es el byte inicial en el objeto completo que contiene el fragmento que deseas subir.
- CHUNK_LAST_BYTE es el byte final del objeto completo que contiene el fragmento que deseas subir.
- TOTAL_OBJECT_SIZE es el tamaño total del objeto que deseas subir.
- SESSION_URI es el valor que se mostró en el encabezado Location cuando iniciaste la carga reanudable.
Un ejemplo de Content-Range es Content-Range: bytes 0-524287/2000000. Consulta Content-Range para obtener más información sobre este encabezado.

Si la solicitud se completa de forma correcta, el servidor responde con 308 Resume Incomplete. La respuesta contiene un encabezado Range. Usa el valor superior de este encabezado para determinar dónde comenzar el siguiente fragmento. No debes suponer que el servidor recibió todos los bytes que se enviaron en la solicitud.
Repite los pasos anteriores para cada fragmento restante de los datos que deseas subir.

Una vez que se completa la carga, recibirás una respuesta 200 OK o 201 Created, junto con todos los metadatos asociados al recurso.

Si se interrumpe alguna de las cargas de fragmentos, o si recibes una respuesta 5xx, sigue el procedimiento que se describe en Reanuda una carga interrumpida.

Verifica el estado de una carga reanudable

Si se interrumpe la carga reanudable, o no estás seguro de que se haya completado, puedes verificar su estado:

API de JSON

Usa cURL para llamar a la API de XML con una solicitud de objeto PUT:
```
curl -i -X PUT \
    -H "Content-Length: 0" \
    -H "Content-Range: bytes */OBJECT_SIZE" \
    "SESSION_URI"
```
Donde:
- OBEJCT_SIZE es la cantidad total de bytes en el objeto. Si no sabes cuál es el tamaño completo del objeto, usa * para este valor.
- SESSION_URI es el valor que se mostró en el encabezado Location cuando iniciaste la carga reanudable.

API de XML

Usa cURL para llamar a la API de XML con una solicitud de objeto PUT:
```
curl -i -X PUT \
    -H "Content-Length: 0" \
    -H "Content-Range: bytes */OBJECT_SIZE" \
    "SESSION_URI"
```
Donde:
- OBEJCT_SIZE es la cantidad total de bytes en el objeto. Si no sabes cuál es el tamaño completo del objeto, usa * para este valor.
- SESSION_URI es el valor que se mostró en el encabezado Location cuando iniciaste la carga reanudable.

Una respuesta 200 OK o 201 Created indica que se completó la carga y que no es necesario realizar ninguna otra acción.

Una respuesta 308 Resume Incomplete indica que debes seguir subiendo el archivo.

Si Cloud Storage aún no recibió bytes, la respuesta 308 no tiene un encabezado Range. En este caso, debes comenzar la carga desde el principio.
De lo contrario, la respuesta 308 tiene un encabezado Range, que especifica qué bytes recibió Cloud Storage hasta el momento. Usa este valor cuando reanudes una carga interrumpida.

Reanuda una carga interrumpida

Si una solicitud de carga se interrumpe antes de que recibas una respuesta, o si recibes una respuesta 503 o 500, debes reanudar la carga interrumpida desde el punto en que se detuvo. Para reanudar una carga interrumpida, haz lo siguiente:

API de JSON

Verifica el estado de la carga reanudable.
Guarda el valor superior del encabezado Range que se encuentra en la respuesta a tu verificación de estado. Si la respuesta no tiene un encabezado Range, Cloud Storage aún no recibió ningún byte, y debes reanudar la carga desde el principio.
Asegúrate de que los datos del objeto que estás a punto de subir comiencen en el byte que le sigue al valor superior en el encabezado Range.
Usa cURL para llamar a la API de JSON con una solicitud de objeto PUT que reanude la carga a partir del byte que le sigue al valor en el encabezado Range:
```
curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \
    -H "Content-Length: UPLOAD_SIZE_REMAINING" \
    -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \
    "SESSION_URI"
```
Donde:
- PARTIAL_OBJECT_LOCATION es la ruta de acceso local a la parte restante de los datos que deseas subir.
- UPLOAD_SIZE_REMAINING es la cantidad de bytes que subes en la solicitud actual. Por ejemplo, la carga del resto de un objeto con un tamaño total de 20,000,000 que se interrumpió después de haber subido los bytes 0-42 tendría un UPLOAD_SIZE_REMAINING de 1999957.
- NEXT_BYTE es el siguiente número entero después del valor que guardaste en el paso 2. Por ejemplo, si 42 es el valor superior en el paso 2, el valor de NEXT_BYTE es 43.
- LAST_BYTE es el byte final que contiene esta solicitud PUT. Por ejemplo, para terminar de subir un objeto cuyo tamaño total es 20000000, el valor de LAST_BYTE es 1999999.
- TOTAL_OBJECT_SIZE es el tamaño total del objeto que deseas subir. Por ejemplo, 20000000.
- SESSION_URI es el valor que se mostró en el encabezado Location cuando iniciaste la carga reanudable.

API de XML

Verifica el estado de la carga reanudable.
Guarda el valor superior del encabezado Range que se encuentra en la respuesta a tu verificación de estado. Si la respuesta no tiene un encabezado Range, Cloud Storage aún no recibió ningún byte, y debes reanudar la carga desde el principio.
Asegúrate de que los datos del objeto que estás a punto de subir comiencen en el byte que le sigue al valor superior en el encabezado Range.
Usa cURL para llamar a la API de XML con una solicitud de objeto PUT que reanude la carga a partir del byte que le sigue al valor en el encabezado Range:
```
curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \
    -H "Content-Length: UPLOAD_SIZE_REMAINING" \
    -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \
    "SESSION_URI"
```
Donde:
- PARTIAL_OBJECT_LOCATION es la ruta de acceso local a la parte restante de los datos que deseas subir.
- UPLOAD_SIZE_REMAINING es la cantidad de bytes que subes en la solicitud actual. Por ejemplo, la carga del resto de un objeto con un tamaño total de 20,000,000 que se interrumpió después de haber subido los bytes 0-42 tendría un UPLOAD_SIZE_REMAINING de 1999957.
- NEXT_BYTE es el siguiente número entero después del valor que guardaste en el paso 2. Por ejemplo, si 42 es el valor superior en el paso 2, el valor de NEXT_BYTE es 43.
- LAST_BYTE es el byte final que contiene esta solicitud PUT. Por ejemplo, para terminar de subir un objeto cuyo tamaño total es 20000000, el valor de LAST_BYTE es 1999999.
- TOTAL_OBJECT_SIZE es el tamaño total del objeto que deseas subir. Por ejemplo, 20000000.
- SESSION_URI es el valor que se mostró en el encabezado Location cuando iniciaste la carga reanudable.

Puedes reanudar las cargas tantas veces como sea necesario mientras el URI de sesión esté activo. El URI de la sesión vence después de una semana. Cuando el archivo se sube de forma correcta, Cloud Storage responde con un código de estado 200 OK o 201 created.

Cancela una carga

Para cancelar una carga reanudable y evitar que se realicen más acciones, sigue estos pasos:

API de JSON

Usa cURL para llamar a la API de JSON con una solicitud DELETE:
```
curl -i -X DELETE -H "Content-Length: 0" \
  "SESSION_URI"
```
Aquí:
- SESSION_URI es el valor que se mostró en el encabezado Location cuando iniciaste la carga reanudable.

Si la solicitud se completa de forma correcta, la respuesta contendrá un código de estado 499. Los intentos posteriores de consultar o reanudar la carga generarán una respuesta 4xx.

API de XML

Usa cURL para llamar a la API de XML con una solicitud DELETE:
```
curl -i -X DELETE -H "Content-Length: 0" \
  "SESSION_URI"
```
Aquí:
- SESSION_URI es el valor que se mostró en el encabezado Location cuando iniciaste la carga reanudable.

Si se ejecuta de forma correcta, la respuesta contiene un código de estado 204 y los intentos futuros de consultar o reanudar la carga también generan una respuesta 204.

Próximos pasos

Obtén más información sobre las cargas reanudables.
Consulta una descripción general de la API de JSON y la API de XML.
Cargas de transmisiones de tamaño desconocido.
Obtén información para agrupar varias solicitudes por lotes en la API de JSON de Cloud Storage.