Cargas reanudables

Configuración

En esta página, se analizan las cargas reanudables en Cloud Storage. Las cargas reanudables son el método recomendado para subir archivos grandes, ya que no tienes que reiniciarlas desde el principio si hay una falla de red mientras se realiza la carga.

Introducción

Una carga reanudable te permite reanudar las operaciones de transferencia de datos a Cloud Storage después de que una falla de comunicación haya interrumpido el flujo de datos. Las cargas reanudables funcionan mediante el envío de varias solicitudes, cada una de ellas con una parte del objeto que estás subiendo. Esto es diferente a una carga de solicitud única, que contiene todos los datos del objeto en una sola solicitud y se debe reiniciar desde el principio si se genera una falla durante el proceso.

  • Usa una carga reanudable si subes archivos grandes o si subes archivos con una conexión lenta. Por ejemplo, si deseas ver los límites de tamaño que deben tener los archivos para usar cargas reanudables, consulta las consideraciones sobre el tamaño de carga.

  • Una carga reanudable se debe completar en una semana de iniciada, pero se puede cancelar en cualquier momento.

  • Solo una carga reanudable completa aparecerá en tu depósito y, si corresponde, reemplaza un objeto existente con el mismo nombre.

    • La hora de creación del objeto se basa en la finalización de la carga.

    • Cualquier metadato de objeto que configure el usuario se especifica en la solicitud inicial. Estos metadatos se aplican al objeto una vez que se completa la carga.

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

Cómo las herramientas y las API usan las cargas reanudables

Según cómo interactúes con Cloud Storage, las cargas reanudables se pueden administrar de forma automática en tu nombre. En esta sección, se describe el comportamiento de carga reanudable para diferentes herramientas y se proporciona orientación sobre cómo configurar el tamaño del búfer adecuado para tu aplicación.

Console

La consola de Google Cloud administra las cargas reanudables de forma automática en tu nombre. Sin embargo, si actualizas o sales de la consola de Google Cloud mientras se realiza una carga, esta se cancela.

Línea de comandos

La herramienta gcloud CLI usa cargas reanudables en los comandos gcloud storage cp y gcloud storage rsync cuando subes datos a Cloud Storage. Si se interrumpe la carga, puedes reanudarla con el mismo comando que usaste para iniciarla. Cuando reanudes una carga que incluya varios archivos, usa la marca --no-clobber para evitar volver a subir archivos que ya se completaron de forma correcta.

Bibliotecas cliente

Cuando se realizan cargas reanudables, las bibliotecas cliente funcionan como wrappers alrededor de la API de JSON de Cloud Storage.

C++

Las funciones en storage::Client se comportan de manera diferente:

De forma predeterminada, UploadFile() realiza una carga reanudable cuando el objeto supera los 20 MiB. De lo contrario, realiza una carga simple o multiparte. Para configurar este umbral, configura MaximumSimpleUploadsSizeOption cuando crees un storage::Client.

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

La biblioteca 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(), recomendamos que consideres las compensaciones entre la velocidad de carga y el uso de memoria. El uso de búferes pequeños para subir objetos grandes puede hacer que la carga sea lenta. Para obtener más información sobre la relación entre la velocidad de carga y el tamaño del búfer para C++, consulta el análisis detallado en GitHub.

C#

Durante la carga, la biblioteca cliente de C# siempre realiza cargas reanudables. Puedes iniciar una carga reanudable con CreateObjectUploader.

La biblioteca cliente de C# usa un tamaño de búfer igual al tamaño del fragmento. El tamaño del búfer predeterminado es de 10 MB y puedes cambiar este valor si configuras ChunkSize en UploadObjectOptions. El tamaño del búfer debe ser un múltiplo de 256 KiB (256 x 1024 bytes). Por lo general, los tamaños de búfer 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.

Go

De forma predeterminada, las cargas reanudables se realizan automáticamente cuando el archivo supera los 16 MiB. Cambias el corte para realizar cargas reanudables con Writer.ChunkSize. Las cargas reanudables siempre se dividen cuando se usa la biblioteca cliente de Go.

Las cargas multiparte se producen cuando el objeto es más pequeño que Writer.ChunkSize o cuando Writer.ChunkSize se establece en 0, donde la fragmentación se inhabilita. El Writer no puede reintentar las solicitudes si ChunkSize se configuró en 0.

La biblioteca 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). Por lo general, los tamaños de búfer 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. Si ejecutas varias cargas reanudables de forma simultánea, debes configurar Writer.ChunkSize en un valor inferior a 16 MiB para evitar el aumento de memoria.

Ten en cuenta que el objeto no finaliza en Cloud Storage hasta que llamas a Writer.Close() y recibes una respuesta exitosa. Writer.Close muestra un error si la solicitud no se realiza de forma correcta.

Java

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

El tamaño del búfer predeterminado es de 15 MiB. Para configurar el tamaño del búfer, puedes usar el método WriteChannel#setChunkSize(int) o pasar un parámetro bufferSize al método Storage#createFrom. El tamaño del búfer tiene un mínimo de 256 KiB. Cuando llamas a WriteChannel#setChunkSize(int) de forma interna, el tamaño del búfer se cambia a un múltiplo de 256 KiB.

El almacenamiento en búfer para cargas reanudables funciona como un umbral de vaciado mínimo, en el que las escrituras más pequeñas que el tamaño del búfer se almacenan en búfer hasta que una escritura aumenta la cantidad de bytes almacenados en búfer por encima del tamaño del búfer.

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

Node.js

Las cargas reanudables se producen de forma automática. Puedes desactivar las cargas reanudables si configuras resumable en UploadOptions como false. Las cargas reanudables se administran de forma automática cuando se usa el método createWriteStream.

No hay un tamaño de búfer predeterminado y las cargas fragmentadas se deben invocar de forma manual mediante la configuración de la opción chunkSize en CreateResumableUploadOptions. Si se especifica chunkSize, los datos se envían en solicitudes HTTP separadas, cada una con una carga útil de tamaño chunkSize. Si no se especifica chunkSize y la biblioteca realiza una carga reanudable, todos los datos se transmiten a una sola solicitud HTTP.

La biblioteca 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). Por lo general, los tamaños de búfer 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.

PHP

De forma predeterminada, las cargas reanudables se realizan automáticamente cuando el tamaño del objeto supera los 5 MB. De lo contrario, se realizarán cargas multiparte. No se puede cambiar este umbral. Para forzar una carga reanudable, configura la opción resumable en la función upload.

La biblioteca cliente de PHP usa un tamaño de búfer igual al tamaño del fragmento. 256 KiB es el tamaño del búfer predeterminado para una carga reanudable, y puedes cambiar el tamaño del búfer si configuras la propiedad chunkSize. El tamaño del búfer debe ser un múltiplo de 256 KiB (256 x 1024 bytes). Por lo general, los tamaños de búfer 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.

Python

Las cargas reanudables se producen cuando el objeto supera los 8 MiB y las cargas multiparte se producen cuando el objeto tiene menos de 8 MiB. Este umbral no puede cambiarse. La biblioteca 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 para una carga reanudable, y puedes cambiar el tamaño del búfer si configuras la propiedad blob.chunk_size.

Para realizar siempre una carga reanudable sin importar el tamaño del objeto, usa la clase storage.BlobWriter o el método storage.Blob.open(mode='w'). Para estos métodos, el tamaño del búfer predeterminado es de 40 MiB. También puedes usar Resumable Media para administrar las cargas reanudables.

El tamaño del fragmento debe ser un múltiplo de 256 KiB (256 x 1024 bytes). 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.

Ruby

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

API de REST

API de JSON

La API de JSON de Cloud Storage usa una solicitud POST Object que incluye el parámetro de búsqueda uploadType=resumable para iniciar la carga reanudable. Esta solicitud se muestra como un URI de sesión que puedes usar en una o más solicitudes PUT Object para subir los datos del objeto. Si deseas obtener una guía paso a paso a fin de compilar tu propia lógica para la carga reanudable, consulta la sección sobre cómo realizar cargas reanudables.

API de XML

La API de XML de Cloud Storage usa una solicitud POST Object que incluye el encabezado x-goog-resumable: start para iniciar la carga reanudable. Esta solicitud se muestra como un URI de sesión que puedes usar en una o más solicitudes PUT Object para subir los datos del objeto. Si deseas obtener una guía paso a paso a fin de compilar tu propia lógica para la carga reanudable, consulta la sección sobre cómo realizar cargas reanudables.

Cargas reanudables de tamaño desconocido

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

Para obtener más información, consulta Cargas de transmisión.

Rendimiento de la carga

Elige regiones de sesión

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

Si usas una instancia de Compute Engine para iniciar una carga reanudable, la instancia debe estar en la misma ubicación que el bucket de Cloud Storage en el que realizas la carga. Puedes usar un servicio de IP geográfico para seleccionar la región de Compute Engine a la que enrutarás las solicitudes de los clientes, lo que te ayuda a tener el tráfico ubicado en una región geográfica.

Sube 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. Sin la fragmentación, se quitan los costos de latencia y los cargos de operación agregados por las consultas de desplazamiento persistente de cada fragmento, y se mejora la capacidad de procesamiento. Sin embargo, debes considerar subir el contenido en fragmentos en los siguientes casos:

  • Tus datos de origen se generan de forma dinámica y quieres limitar la cantidad que necesitas almacenar en búfer del cliente, en caso de que falle la carga.

  • Tus clientes tienen limitaciones de tamaño de solicitudes, como es el caso de muchos navegadores.

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

Consideraciones

Esta sección es útil si compilas tu propio cliente que envía solicitudes de carga reanudables directamente a la API de JSON o XML.

URI de sesión

Cuando inicias una carga reanudable, Cloud Storage muestra un URI de sesión, que se usa en solicitudes posteriores para subir los datos reales. Este es un ejemplo de un URI de sesión en la API de JSON:

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

Este es un ejemplo de un URI de sesión en la API de XML:

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

Este URI de sesión actúa como un token de autenticación, por lo que no es necesario firmar las solicitudes que lo usan y cualquier persona puede subir datos al bucket de destino sin ninguna autenticación adicional. Debido a esto, sé prudente cuando compartas el URI de sesión y compártelo solo a través de HTTPS.

Los URI de sesión vencen después de una semana, pero se pueden cancelar antes de que venzan. Si realizas 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 pasó menos de una semana desde que se inició la carga.
  • Un código de estado 404 Not Found si pasó más de una semana desde que se inició la carga.

En ambos casos, debes iniciar una nueva carga reanudable, obtener un nuevo URI de sesión y comenzar la carga desde el principio con el nuevo URI de sesión.

Verificaciones de integridad

Recomendamos que solicites una verificación de integridad del objeto final subido para asegurarte de que coincida con el archivo de origen. Para ello, calcula el resumen MD5 del archivo de origen y agrégalo al encabezado de la solicitud Content-MD5.

Verificar la integridad del archivo subido es importante, en especial, si subes un archivo grande durante un período prolongado, ya que hay una mayor probabilidad de que el archivo de origen se modifique en el transcurso de la operación de carga.

Cuando se inicia una carga reanudable, se ignorará el valor x-goog-content-sha256. Por lo tanto, se recomienda establecer x-goog-content-sha256 en UNSIGNED-PAYLOAD.

Reintenta y reenvía datos

Una vez que Cloud Storage conserva bytes en una carga reanudable, esos bytes no se pueden reemplazar y Cloud Storage ignora los intentos de hacerlo. Debido a esto, no debes enviar datos diferentes cuando se revierte a una compensación que enviaste anteriormente.

Por ejemplo, supongamos que subes un objeto de 100,000 bytes y tu conexión se interrumpe. Cuando verificas el estado, descubres que se subieron y almacenaron con éxito 50,000 bytes. Si intentas reiniciar la carga en el byte 40,000, Cloud Storage ignora los bytes entre 40,000 y 50,000 que enviaste. Cloud Storage comienza a conservar los datos que envías en el byte 50,001.

¿Qué sigue?