Subidas reanudables

Configuración

En esta página se explica cómo funcionan las subidas reanudables en Cloud Storage. Las subidas reanudables son el método recomendado para subir archivos de gran tamaño, ya que no tienes que reiniciarlas desde el principio si se produce un fallo en la red mientras se está realizando la subida.

Introducción

Una subida reanudable te permite reanudar las operaciones de transferencia de datos a Cloud Storage después de que un fallo de comunicación haya interrumpido el flujo de datos. Las subidas reanudables funcionan enviando varias solicitudes, cada una de las cuales contiene una parte del objeto que estás subiendo. Esto es diferente de una subida con una sola solicitud, que contiene todos los datos del objeto en una sola solicitud y debe reiniciarse desde el principio si falla a mitad del proceso.

  • Utiliza una subida reanudable si vas a subir archivos grandes o si la conexión es lenta. Por ejemplo, los límites de tamaño de archivo para usar subidas reanudables. Consulta las consideraciones sobre el tamaño de subida.

  • Una subida reanudable debe completarse en un plazo de una semana desde que se inicia, pero se puede cancelar en cualquier momento.

  • Solo se mostrará en tu segmento una subida reanudable completada y, si procede, se sustituirá un objeto con el mismo nombre.

    • La hora de creación del objeto se basa en el momento en que se completa la subida.

    • Los metadatos de objeto definidos por el usuario se especifican en la solicitud inicial. Estos metadatos se aplican al objeto una vez que se completa la subida.

    • La API JSON también admite la configuración de metadatos personalizados en la solicitud final si incluye encabezados con el prefijo X-Goog-Meta- en esa solicitud.

Cómo usan las herramientas y las APIs las subidas reanudables

En función de cómo interactúes con Cloud Storage, las subidas reanudables se pueden gestionar automáticamente en tu nombre. En esta sección se describe el comportamiento de la subida reanudable de diferentes herramientas y se ofrecen directrices sobre cómo configurar el tamaño de búfer adecuado para tu aplicación.

Consola

La consola Google Cloud gestiona las subidas reanudables automáticamente en tu nombre. Sin embargo, si actualizas la consolaGoogle Cloud o te desplazas a otra página mientras se está subiendo un archivo, la subida se cancelará.

Línea de comandos

La CLI gcloud usa subidas reanudables en los comandos gcloud storage cp y gcloud storage rsync al subir datos a Cloud Storage. Si se interrumpe la subida, puedes reanudarla ejecutando el mismo comando que usaste para iniciarla. Cuando reanudes una subida de este tipo que incluya varios archivos, usa la marca --no-clobber para evitar que se vuelvan a subir los archivos que ya se hayan completado correctamente.

Bibliotecas de cliente

Cuando se realizan subidas reanudables, las bibliotecas de cliente funcionan como envoltorios de la API JSON de Cloud Storage.

C++

Las funciones de storage::Client se comportan de forma diferente:

De forma predeterminada, UploadFile() realiza una subida reanudable cuando el objeto es mayor de 20 MiB. De lo contrario, realiza una subida simple o una subida multiparte. Puedes configurar este umbral definiendo MaximumSimpleUploadsSizeOption al crear un storage::Client.

8 MiB es el tamaño de búfer predeterminado, que puedes modificar con la opción UploadBufferSizeOption.

La biblioteca de cliente de C++ usa un tamaño de búfer igual al tamaño del fragmento. El tamaño del búfer debe ser un múltiplo de 256 KiB (256 x 1024 bytes). Cuando uses WriteObject() y UploadFile(), te recomendamos que tengas en cuenta el equilibrio entre la velocidad de subida y el uso de memoria. Si usas búferes pequeños para subir objetos grandes, el proceso puede ser lento. Para obtener más información sobre la relación entre la velocidad de subida y el tamaño del búfer en C++, consulta el análisis detallado en GitHub.

C#

Al subir contenido, la biblioteca de cliente de C# siempre realiza subidas reanudables. Puedes iniciar una subida reanudable con CreateObjectUploader.

La biblioteca de cliente de C# usa un tamaño de búfer igual al tamaño del fragmento. El tamaño de búfer predeterminado es de 10 MB y puedes cambiar este valor configurando ChunkSize en UploadObjectOptions. El tamaño del búfer debe ser un múltiplo de 256 KiB (256 x 1024 bytes). Los tamaños de búfer más grandes suelen acelerar las subidas, pero ten en cuenta que hay un equilibrio entre la velocidad y el uso de memoria.

Go

De forma predeterminada, las subidas reanudables se realizan automáticamente cuando el archivo es superior a 16 MiB. Puedes cambiar el límite para realizar subidas reanudables con Writer.ChunkSize. Las subidas reanudables siempre se dividen en fragmentos cuando se usa la biblioteca de cliente de Go.

Las subidas multiparte se producen cuando el objeto es más pequeño que Writer.ChunkSize o cuando Writer.ChunkSize es 0, en cuyo caso se inhabilita la fragmentación. El Writer no puede volver a intentar las solicitudes si ChunkSize tiene el valor 0.

La biblioteca de cliente de Go usa un tamaño de búfer igual al tamaño del fragmento. El tamaño del búfer debe ser un múltiplo de 256 KiB (256 x 1024 bytes). Los tamaños de búfer más grandes suelen acelerar las subidas, pero ten en cuenta que hay un equilibrio entre la velocidad y el uso de memoria. Si estás ejecutando varias subidas reanudables simultáneamente, debes asignar a Writer.ChunkSize un valor inferior a 16 MiB para evitar que se agote la memoria.

Ten en cuenta que el objeto no se finaliza en Cloud Storage hasta que llamas a Writer.Close() y recibes una respuesta de éxito. Writer.Close devuelve un error si la solicitud no se realiza correctamente.

Java

La biblioteca de cliente de Java tiene métodos independientes para las subidas multiparte y reanudables. Los siguientes métodos siempre realizan una subida reanudable:

El tamaño de búfer predeterminado es de 15 MiB. Puedes definir el tamaño del búfer mediante el método WriteChannel#setChunkSize(int) o pasando un parámetro bufferSize al método Storage#createFrom. El tamaño del búfer tiene un mínimo fijo de 256 KiB. Cuando se llama a WriteChannel#setChunkSize(int) internamente, el tamaño del búfer se cambia a un múltiplo de 256 KiB.

El almacenamiento en búfer de las subidas reanudables funciona como umbral mínimo de vaciado, donde las escrituras más pequeñas que el tamaño del búfer se almacenan en búfer hasta que una escritura supera el tamaño del búfer.

Si va a subir cantidades de datos más pequeñas, puede usar Storage#create(BlobInfo, byte[], Storage.BlobTargetOption...) o Storage#create(BlobInfo, byte[], int, int, Storage.BlobTargetOption...).

Node.js

Las subidas reanudables se realizan automáticamente. Para desactivar las subidas reanudables, define resumable en UploadOptions como false. Las subidas reanudables se gestionan automáticamente cuando se usa el método createWriteStream.

No hay ningún tamaño de búfer predeterminado y las subidas fragmentadas se deben invocar manualmente configurando la opción chunkSize en CreateResumableUploadOptions. Si se especifica chunkSize, los datos se envían en solicitudes HTTP independientes, cada una con una carga útil de tamaño chunkSize. Si no se especifica ningún chunkSize y la biblioteca está realizando una subida reanudable, todos los datos se transmiten en una sola solicitud HTTP.

La biblioteca de cliente de Node.js usa un tamaño de búfer igual al tamaño del fragmento. El tamaño del búfer debe ser un múltiplo de 256 KiB (256 x 1024 bytes). Los tamaños de búfer más grandes suelen acelerar las subidas, pero ten en cuenta que hay un equilibrio entre la velocidad y el uso de memoria.

PHP

De forma predeterminada, las subidas reanudables se realizan automáticamente cuando el tamaño del objeto es superior a 5 MB. De lo contrario, se producirán subidas multiparte. Este umbral no se puede cambiar. Puedes forzar una subida reanudable configurando la opción resumable en la función upload.

La biblioteca de cliente de PHP usa un tamaño de búfer igual al tamaño del fragmento. 256 KiB es el tamaño de búfer predeterminado para una subida reanudable. Puedes cambiarlo configurando la propiedad chunkSize. El tamaño del búfer debe ser un múltiplo de 256 KiB (256 x 1024 bytes). Los tamaños de búfer más grandes suelen acelerar las subidas, pero ten en cuenta que hay un equilibrio entre la velocidad y el uso de memoria.

Python

Las subidas reanudables se producen cuando el objeto tiene un tamaño superior a 8 MiB, y las subidas en varias partes se producen cuando el objeto tiene un tamaño inferior a 8 MiB. Este umbral no se puede cambiar. La biblioteca de cliente de Python usa un tamaño de búfer igual al tamaño del fragmento. 100 MiB es el tamaño de búfer predeterminado que se usa en las subidas reanudables. Puedes cambiarlo asignando un valor a la propiedad blob.chunk_size.

Para realizar siempre una subida reanudable, independientemente del tamaño del objeto, usa la clase storage.BlobWriter o el método storage.Blob.open(mode='w'). En estos métodos, el tamaño de búfer predeterminado es de 40 MiB. También puedes usar Reanudación de contenido multimedia para gestionar las subidas que se pueden reanudar.

El tamaño del fragmento debe ser un múltiplo de 256 KiB (256 x 1024 bytes). Los tamaños de fragmento más grandes suelen acelerar las subidas, pero ten en cuenta que hay un equilibrio entre la velocidad y el uso de memoria.

Ruby

La biblioteca de cliente de Ruby trata todas las subidas como subidas reanudables no fragmentadas.

APIs REST

API JSON

La API JSON de Cloud Storage usa una solicitud POST Object que incluye el parámetro de consulta uploadType=resumable para iniciar la subida reanudable. Esta solicitud devuelve un URI de sesión que puedes usar en una o varias solicitudes PUT Object para subir los datos del objeto. Para obtener una guía paso a paso sobre cómo crear tu propia lógica para las subidas reanudables, consulta Realizar subidas reanudables.

API XML

La API XML de Cloud Storage usa una solicitud POST Object que incluye el encabezado x-goog-resumable: start para iniciar la subida reanudable. Esta solicitud devuelve un URI de sesión que puedes usar en una o varias solicitudes PUT Object para subir los datos del objeto. Para obtener una guía paso a paso sobre cómo crear tu propia lógica para las subidas reanudables, consulta Realizar subidas reanudables.

Subidas reanudables de tamaño desconocido

El mecanismo de subida reanudable admite transferencias en las que no se conoce el tamaño del archivo de antemano. Esto puede ser útil en casos como la compresión de un objeto sobre la marcha durante la subida, ya que es difícil predecir el tamaño exacto del archivo comprimido al inicio de una transferencia. Este mecanismo es útil si quieres transmitir una transferencia que se pueda reanudar después de interrumpirse o si la codificación de transferencia fragmentada no funciona en tu aplicación.

Para obtener más información, consulta Subidas de streaming.

Rendimiento de subida

Elegir regiones de sesiones

Las subidas reanudables se fijan en la región en la que las inicias. Por ejemplo, si inicias una subida reanudable en EE. UU. y proporcionas el URI de sesión a un cliente de Asia, la subida se seguirá realizando en EE. UU. Para reducir el tráfico entre regiones y mejorar el rendimiento, debes mantener una sesión de subida reanudable en la región en la que se creó.

Si usas una instancia de Compute Engine para iniciar una subida reanudable, la instancia debe estar en la misma ubicación que el segmento de Cloud Storage al que subas el contenido. Después, puedes usar un servicio de IP geográfica para elegir la región de Compute Engine a la que dirigir las solicitudes de los clientes, lo que ayuda a mantener el tráfico localizado en una región geográfica.

Subir contenido en fragmentos

Si es posible, evita dividir una transferencia en fragmentos más pequeños y, en su lugar, sube todo el contenido en un solo fragmento. Si evitas la fragmentación, se eliminan los costes de latencia y las tarifas de operaciones adicionales de la consulta del desplazamiento persistente de cada fragmento, así como se mejora el rendimiento. Sin embargo, te recomendamos que subas los archivos en fragmentos cuando:

  • Los datos de origen se generan de forma dinámica y quieres limitar la cantidad que necesitas almacenar en el búfer del lado del cliente por si falla la subida.

  • Tus clientes tienen limitaciones de tamaño de solicitud, como ocurre con muchos navegadores.

Si usas la API JSON o XML y tu cliente recibe un error, puede consultar al servidor el desplazamiento persistente y reanudar la subida de los bytes restantes a partir de ese desplazamiento. La Google Cloud consola, la CLI de Google Cloud y las bibliotecas de cliente se encargan de esto automáticamente. Consulta Cómo usan las herramientas y las APIs las subidas reanudables para obtener más información sobre la fragmentación en bibliotecas de cliente específicas.

Cuestiones importantes

Esta sección es útil si estás creando tu propio cliente que envía solicitudes de subida reanudable directamente a la API JSON o XML.

URIs de sesión

Cuando inicias una subida reanudable, Cloud Storage devuelve un URI de sesión, que usas en solicitudes posteriores para subir los datos reales. Un ejemplo de URI de sesión en la API JSON es el siguiente:

https://storage.googleapis.com/upload/storage/v1/b/my-bucket/o?uploadType=resumable&name=my-file.jpg&upload_id=ABg5-UxlRQU75tqTINorGYDgM69mX06CzKO1NRFIMOiuTsu_mVsl3E-3uSVz65l65GYuyBuTPWWICWkinL1FWcbvvOA

Un ejemplo de URI de sesión en la API XML es el siguiente:

 https://storage.googleapis.com/my-bucket/my-file.jpg?upload_id=ABg5-UxlRQU75tqTINorGYDgM69mX06CzKO1NRFIMOiuTsu_mVsl3E-3uSVz65l65GYuyBuTPWWICWkinL1FWcbvvOA

Este URI de sesión actúa como token de autenticación, por lo que las solicitudes que lo usan no necesitan estar firmadas y cualquier persona puede usarlas para subir datos al segmento de destino sin necesidad de autenticación adicional. Por este motivo, debes ser prudente al compartir el URI de sesión y solo compartirlo a través de HTTPS.

El URI de una sesión caduca al cabo de una semana, pero se puede cancelar antes de que caduque. Si haces una solicitud con un URI de sesión que ya no es válido, recibirás uno de los siguientes errores:

  • Un código de estado 410 Gone si ha transcurrido menos de una semana desde que se inició la subida.
  • Un código de estado 404 Not Found si ha transcurrido más de una semana desde que se inició la subida.

En ambos casos, o si pierde el URI de sesión antes de que se complete la subida, deberá iniciar una nueva subida reanudable, obtener un nuevo URI de sesión y empezar la subida desde el principio con el nuevo URI de sesión.

Comprobaciones de integridad

Te recomendamos que solicites una comprobación de integridad del objeto final subido para asegurarte de que coincide con el archivo de origen. Para ello, calcula el resumen MD5 del archivo de origen y añádelo al encabezado de la solicitud Content-MD5.

Comprobar la integridad del archivo subido es especialmente importante si vas a subir un archivo de gran tamaño durante un periodo prolongado, ya que aumenta la probabilidad de que el archivo de origen se modifique durante la operación de subida.

Sin embargo, no puedes realizar comprobaciones de integridad en partes intermedias o fragmentos de una subida reanudable, ya que estas subidas están pensadas para que puedas reanudar una subida en caso de que se interrumpa de forma inesperada.

Reintentos y reenvío de datos

Una vez que Cloud Storage persiste los bytes en una subida reanudable, esos bytes no se pueden sobrescribir y Cloud Storage ignora los intentos de hacerlo. Por este motivo, no debes enviar datos diferentes al volver a un desplazamiento que hayas enviado anteriormente.

Por ejemplo, supongamos que está subiendo un objeto de 100.000 bytes y su conexión se interrumpe. Al comprobar el estado, ves que se han subido y conservado correctamente 50.000 bytes. Si intentas reiniciar la subida en el byte 40.000, Cloud Storage ignora los bytes que envías del 40.000 al 50.000. Cloud Storage empieza a conservar los datos que envías en el byte 50.001.

Siguientes pasos