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.
Para obtener información sobre el uso de cargas reanudables en Google Cloud CLI y las bibliotecas cliente, consulta Cómo las APIs y herramientas usan las cargas reanudables.
Roles obligatorios
A fin de obtener los permisos que necesitas para realizar una carga reanudable, pídele a tu administrador que te otorgue uno de los siguientes roles:
Para las cargas que incluyen un bloqueo de retención de objetos, pídele a tu administrador que te otorgue el rol de IAM de Administrador de objetos de almacenamiento (
roles/storage.objectAdmin
) para el bucket.Para todos los demás casos, pídele a tu administrador que te otorgue el rol de IAM de usuario de objeto de almacenamiento (
roles/storage.objectUser
) para el bucket.
Estos roles predefinidos contienen los permisos necesarios para subir un objeto a un bucket en sus respectivos casos. Para ver los permisos exactos que son necesarios, expande la sección Permisos necesarios:
Permisos necesarios
storage.objects.create
storage.objects.delete
- Este permiso solo es necesario para las cargas que reemplazan un objeto existente.
storage.objects.setRetention
- Este permiso solo es necesario para las cargas que incluyen un bloqueo de retención de objetos.
También puedes obtener estos permisos con otros roles predefinidos o roles personalizados.
Para obtener más información sobre cómo otorgar roles en los buckets, consulta Usa IAM con buckets.
Inicia una sesión de carga reanudable
Para iniciar una sesión de carga reanudable, haz lo siguiente:
API de JSON
Tener la gcloud CLI instalada e inicializadaa fin de generar un token de acceso para el encabezado
Authorization
.Como alternativa, puedes crear un token de acceso con OAuth 2.0 Playground y, luego, incluirlo en el encabezado
Authorization
.De manera opcional, crea un archivo que contenga los metadatos que deseas configurar en el objeto que deseas subir. Por ejemplo, en el siguiente archivo JSON, se establecen los metadatos
contentType
del objeto que deseas subir aimage/png
:{ "contentType": "image/png" }
Usa
cURL
para llamar a la API de JSON con una solicitud de objetoPOST
:curl -i -X POST --data-binary @METADATA_LOCATION \ -H "Authorization: Bearer $(gcloud auth print-access-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 encabezadoContent-Type
.INITIAL_REQUEST_LENGTH
es la cantidad de bytes en el cuerpo de esta solicitud inicial, por ejemplo,79
.BUCKET_NAME
es el nombre del bucket al que subes el objeto. Por ejemplo,my-bucket
.OBJECT_NAME
es el nombre codificado en URL que deseas darle a tu objeto. Por ejemplo,pets/dog.png
, codificado en URL comopets%2Fdog.png
. Esto no es necesario si incluiste unname
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
yX-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 objetoPOST
.Este URI se usa en las solicitudes posteriores para subir los datos del objeto.
API de XML
Tener la gcloud CLI instalada e inicializadaa fin de generar un token de acceso para el encabezado
Authorization
.Como alternativa, puedes crear un token de acceso con OAuth 2.0 Playground y, luego, incluirlo en el encabezado
Authorization
.Usa
cURL
para llamar a la API de XML con una solicitud de objetoPOST
que tenga un cuerpo vacío:curl -i -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Length: 0" \ -H "Content-Type: OBJECT_CONTENT_TYPE" \ -H "x-goog-resumable: start" \ "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"
Aquí:
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 metadatosContent-Type
para que el objeto seaapplication/octet-stream
.BUCKET_NAME
es el nombre del depósito al que subes el objeto. Por ejemplo,my-bucket
.OBJECT_NAME
es el nombre codificado en URL que deseas darle a tu objeto. Por ejemplo,pets/dog.png
, codificado en URL comopets%2Fdog.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 objetoPOST
.Este URI se usa en las solicitudes posteriores para subir los datos del objeto.
suba los datos
Una vez que inicias una carga reanudable, hay dos formas de subir los datos del objeto:
- En un solo fragmento: 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 un solo fragmento
Para subir los datos en un solo fragmento, sigue estos pasos:
API de JSON
Usa
cURL
para llamar a la API de JSON con una solicitud de objetoPUT
: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 encabezadoLocation
cuando iniciaste la carga reanudable.
De manera opcional, puedes incluir encabezados con el prefijo
X-Goog-Meta-
para agregar metadatos personalizados del objeto como parte de esta solicitud.
API de XML
Usa
cURL
para llamar a la API de XML con una solicitud de objetoPUT
: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 encabezadoLocation
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 los datos en varios fragmentos, sigue estos pasos:
API de JSON
Crea un fragmento de datos a partir de los datos generales 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 rápidas, pero ten en cuenta que hay una relación entre la velocidad y el uso de la memoria. Se recomienda usar al menos 8 MiB para el tamaño del fragmento.
Usa
cURL
para llamar a la API de JSON con una solicitud de objetoPUT
: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,8388608
.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 encabezadoLocation
cuando iniciaste la carga reanudable.
Un ejemplo de
Content-Range
esContent-Range: bytes 0-8388607/20000000
. ConsultaContent-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 encabezadoRange
.Repite los pasos anteriores para cada fragmento restante de datos que desees subir y usa el valor superior que contiene el encabezado
Range
de cada respuesta para determinar dónde comenzar cada fragmento sucesivo. No debes suponer que el servidor recibió todos los bytes que se enviaron en una solicitud determinada.De manera opcional, en la solicitud final de la carga reanudable, puedes incluir encabezados con el prefijo
X-Goog-Meta-
para agregar metadatos personalizados del objeto.
API de XML
Crea un fragmento de datos a partir de los datos generales 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 rápidas, pero ten en cuenta que hay una relación entre la velocidad y el uso de la memoria. Se recomienda usar al menos 8 MiB para el tamaño del fragmento.
Usa
cURL
para llamar a la API de XML con una solicitud de objetoPUT
: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,8388608
.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 encabezadoLocation
cuando iniciaste la carga reanudable.
Un ejemplo de
Content-Range
esContent-Range: bytes 0-8388607/20000000
. ConsultaContent-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 encabezadoRange
.Repite los pasos anteriores para cada fragmento restante de datos que desees subir y usa el valor superior que contiene el encabezado
Range
de cada respuesta para determinar dónde comenzar cada fragmento sucesivo. No debes suponer que el servidor recibió todos los bytes que se enviaron en una solicitud determinada.
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
, debes reenviar el fragmento interrumpido en su totalidad o reanudar la carga interrumpida desde el punto en que se detuvo.
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 JSON con una solicitud de objetoPUT
:curl -i -X PUT \ -H "Content-Length: 0" \ -H "Content-Range: bytes */OBJECT_SIZE" \ "SESSION_URI"
Aquí:
OBJECT_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 encabezadoLocation
cuando iniciaste la carga reanudable.
API de XML
Usa
cURL
para llamar a la API de XML con una solicitud de objetoPUT
:curl -i -X PUT \ -H "Content-Length: 0" \ -H "Content-Range: bytes */OBJECT_SIZE" \ "SESSION_URI"
Donde:
OBJECT_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 encabezadoLocation
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 los datos.
- Si Cloud Storage aún no conserva ningún byte, la respuesta
308
no tiene un encabezadoRange
. En este caso, debes comenzar la carga desde el principio. - De lo contrario, la respuesta
308
tiene un encabezadoRange
, que especifica qué bytes conserva 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 encabezadoRange
, Cloud Storage aún no conservó 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
.Si la solicitud interrumpida contenía encabezados con el prefijo
X-Goog-Meta-
, incluye esos encabezados en la solicitud para reanudar tu carga.Usa
cURL
para llamar a la API de JSON con una solicitud de objetoPUT
que reanude la carga a partir del byte que le sigue al valor en el encabezadoRange
: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 unUPLOAD_SIZE_REMAINING
de19999957
.NEXT_BYTE
es el siguiente número entero después del valor que guardaste en el paso 2. Por ejemplo, si42
es el valor superior en el paso 2, el valor deNEXT_BYTE
es43
.LAST_BYTE
es el byte final que contiene esta solicitudPUT
. Por ejemplo, para terminar de subir un objeto cuyo tamaño total es20000000
, el valor deLAST_BYTE
es19999999
.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 encabezadoLocation
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 encabezadoRange
, Cloud Storage aún no conservó 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 objetoPUT
que reanude la carga a partir del byte que le sigue al valor en el encabezadoRange
: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 unUPLOAD_SIZE_REMAINING
de19999957
.NEXT_BYTE
es el siguiente número entero después del valor que guardaste en el paso 2. Por ejemplo, si42
es el valor superior en el paso 2, el valor deNEXT_BYTE
es43
.LAST_BYTE
es el byte final que contiene esta solicitudPUT
. Por ejemplo, para terminar de subir un objeto cuyo tamaño total es20000000
, el valor deLAST_BYTE
es19999999
.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 encabezadoLocation
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 los datos se suben 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 incompleta 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 solicitudDELETE
:curl -i -X DELETE -H "Content-Length: 0" \ "SESSION_URI"
Aquí:
SESSION_URI
es el valor que se mostró en el encabezadoLocation
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 solicitudDELETE
:curl -i -X DELETE -H "Content-Length: 0" \ "SESSION_URI"
Aquí:
SESSION_URI
es el valor que se mostró en el encabezadoLocation
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
.
¿Qué sigue?
- 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.
- Agrupa varias solicitudes a la API de JSON de Cloud Storage.