Cargas compuestas paralelas

Nota: Si interactúas con Cloud Storage a través de la API de XML, considera usar cargas multiparte de la API de XML en lugar de cargas compuestas paralelas: las cargas multiparte API de XML admiten una mayor cantidad de partes que las operaciones de composición, tienen menos posibilidades de tarifas por eliminación temprana y no requieren solicitudes Delete para quitar las partes de origen una vez que se ensambla el objeto final.

Una estrategia para cargar archivos grandes se denomina carga compuesta paralela. En esta carga, se divide un archivo en hasta 32 fragmentos, los fragmentos se suben en paralelo a objetos temporales, el objeto final se vuelve a crear mediante los objetos temporales y, luego, se borran los objetos temporales.

Las cargas compuestas paralelas pueden ser mucho más rápidas si la velocidad de la red y el disco no son factores limitantes. Sin embargo, el objeto final almacenado en el bucket es un objeto compuesto, que solo tiene un hash crc32c y no un hash MD5. Como resultado, debes usar crcmod para realizar verificaciones de integridad cuando descargas el objeto con aplicaciones de Python. Solo debes realizar cargas compuestas paralelas si se aplica lo siguiente:

• No necesitas que los objetos subidos tengan un hash MD5.

• Cualquier usuario de Python, incluidos los usuarios de gsutil, que necesite descargar los objetos tiene instalado google-crc32c o crcmod.

  Por ejemplo, si usas Python para subir recursos de video que solo entrega una aplicación de Java, las cargas compuestas paralelas son una buena opción porque hay implementaciones eficientes de CRC32C disponibles en Java.

Advertencia: Las cargas compuestas paralelas implican borrar los objetos temporales. Ten en cuenta lo siguiente:

• Para minimizar la facturación de los objetos temporales, bórralos de forma definitiva durante el proceso de composición.
• Si planeas borrar los objetos temporales después de que finalice el proceso de composición, usa Standard storage para los objetos temporales y evita las tarifas de eliminación temprana que se cobran por otras clases de almacenamiento. Una vez que se compone el objeto final, puedes cambiar la clase de almacenamiento.
• Si tu bucket tiene habilitadas funciones de protección de datos, como la eliminación no definitiva o el control de versiones de objetos, borrar objetos temporales después de que finalice el proceso de composición puede aumentar significativamente tu factura de almacenamiento. Considera inhabilitar estas protecciones en tu bucket si realizas cargas compuestas paralelas con frecuencia. Como alternativa, borra de forma definitiva los objetos temporales durante el proceso de composición
• No debes usar cargas compuestas paralelas en los bucket que tienen una política de retención, ya que los objetos temporales no se pueden borrar hasta que cumplan con el período de retención.
• Si el bucket que subas tiene retenciones de objetos predeterminadas habilitadas, debes liberar la retención de cada objeto temporal antes de poder bórralo.

Roles obligatorios

Para obtener los permisos que necesitas para realizar cargas compuestas paralelas, pídele a tu administrador que te otorgue el rol de IAM de usuario de objetos de almacenamiento (roles/storage.objectUser) en el bucket.

El rol de administrador de almacenamiento (roles/storage.admin) contiene los permisos necesarios para subir, leer y borrar fragmentos de objetos. También contiene el permiso necesario para que gcloud CLI realice una verificación de compatibilidad a nivel del bucket con cargas compuestas paralelas. Si no puedes obtener el rol de administrador de almacenamiento (roles/storage.admin), puedes realizar cargas compuestas paralelas con la gcloud CLI si obtienes el rol de Usuario de objetos de almacenamiento (roles/storage.objectUser) y, luego, inhabilitas la propiedad storage/parallel_composite_upload_compatibility_check. Para obtener más información, consulta la pestaña Línea de comandos en la sección Cómo las herramientas y las APIs usan las cargas compuestas paralelas.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Para obtener instrucciones para otorgar roles a los buckets, consulta Configura y administra políticas de IAM en buckets.

Cómo las herramientas y las APIs usan las cargas compuestas paralelas

Según cómo interactúes con Cloud Storage, las cargas compuestas paralelas pueden administrarse de forma automática en tu nombre. En esta sección, se describe el comportamiento de carga compuesto en paralelo para diferentes herramientas y se proporciona información sobre cómo puedes modificar el comportamiento.

Console

La Google Cloud consola no realiza cargas compuestas paralelas.

Línea de comandos

Las siguientes propiedades funcionan en conjunto para determinar cómo y cuándo gcloud CLI realiza cargas compuestas paralelas:

• storage/parallel_composite_upload_enabled: propiedad para habilitar las cargas compuestas paralelas. Si es False, inhabilita las cargas compuestas paralelas y omite las verificaciones de compatibilidad a nivel del bucket. Si es True o None, habilita las cargas compuestas paralelas para los objetos que cumplen con los criterios definidos en las otras propiedades y habilita las verificaciones de compatibilidad. La configuración predeterminada es None.

• storage/parallel_composite_upload_compatibility_check: propiedad para activar o desactivar las verificaciones a nivel del bucket de compatibilidad y seguridad con cargas compuestas paralelas. Si es True, gcloud CLI envía una solicitud GET para los metadatos del bucket de destino antes de intentar una carga compuesta paralela, lo que requiere que la principal tenga el permiso storage.buckets.get. Gcloud CLI solo realiza cargas compuestas paralelas cuando se cumplen todas las siguientes condiciones:

  • La clase de almacenamiento para el objeto subido es STANDARD.
  • El bucket de destino no tiene una política de retención.
  • El bucket de destino no tiene conservaciones de objetos predeterminadas habilitadas.

  La configuración predeterminada es True. Si es False, gcloud CLI no realiza la verificación de compatibilidad.

  Si configuras storage/parallel_composite_upload_compatibility_check como False, no se inhabilitan las cargas compuestas paralelas. Cuando storage/parallel_composite_upload_compatibility_check se establece en False y storage/parallel_composite_upload_enabled es None o True, la gcloud CLI omite la verificación del bucket y continúa directamente con una carga compuesta paralela.

  Para omitir esta verificación, inhabilita la propiedad storage/parallel_composite_upload_compatibility_check:

  gcloud config set storage/parallel_composite_upload_compatibility_check False
  

• storage/parallel_composite_upload_threshold: Es el tamaño total mínimo del archivo para realizar una carga compuesta paralela. La configuración predeterminada es de 150 MiB.

• storage/parallel_composite_upload_component_size: Es el tamaño máximo de cada objeto temporal. La propiedad se ignora si el tamaño total del archivo es tan grande que requeriría más de 32 fragmentos en este tamaño

• storage/parallel_composite_upload_component_prefix: Es el prefijo que se usa para nombrar objetos temporales. Esta propiedad se puede establecer como una ruta de acceso absoluta o como una ruta de acceso relativa al objeto final. Consulta la descripción de la propiedad para obtener más información. El prefijo predeterminado es la ruta de acceso absoluta /gcloud/tmp/parallel_composite_uploads/see_gcloud_storage_cp_help_for_details.

Puedes modificar estas propiedades si creas una configuración con nombre y aplicas la configuración por comando usando la --configuration marca de todo el proyecto o para todos los comandos de gcloud CLI con el comando gcloud config set.

No se requiere espacio en el disco local adicional cuando se usa gcloud CLI para realizar cargas compuestas paralelas. Si una carga compuesta paralela falla antes de la composición, ejecuta el comando de gcloud CLI de nuevo para aprovechar las cargas reanudables de los objetos temporales que fallaron. Cualquier objeto temporal que se haya subido de forma correcta antes de la falla, no volverá a subirse cuando reanudes la carga.

Los objetos temporales reciben un nombre de la siguiente manera:

TEMPORARY_PREFIX/RANDOM_VALUE_HEX_DIGEST_COMPONENT_ID

Donde:

• La propiedad storage/parallel_composite_upload_component_prefix controla TEMPORARY_PREFIX.
• RANDOM_VALUE es un valor numérico aleatorio.
• HEX_DIGEST es un hash derivado del nombre del recurso de origen.
• COMPONENT_ID es el número secuencial del componente.

Por lo general, los objetos temporales se borran al final de una carga compuesta paralela. Sin embargo, para evitar que queden objetos temporales, debes verificar el estado de salida del comando de gcloud CLI y borrar de forma manual los objetos temporales que se subieron como parte de cualquier carga anulada.

Bibliotecas cliente

Java

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Java.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

Puedes realizar cargas compuestas paralelas si configuras AllowParallelCompositeUpload como true. Por ejemplo:

import com.google.cloud.storage.transfermanager.ParallelUploadConfig;
import com.google.cloud.storage.transfermanager.TransferManager;
import com.google.cloud.storage.transfermanager.TransferManagerConfig;
import com.google.cloud.storage.transfermanager.UploadResult;
import java.io.IOException;
import java.nio.file.Path;
import java.util.List;

class AllowParallelCompositeUpload {

  public static void parallelCompositeUploadAllowed(String bucketName, List<Path> files)
      throws IOException {
    TransferManager transferManager =
        TransferManagerConfig.newBuilder()
            .setAllowParallelCompositeUpload(true)
            .build()
            .getService();
    ParallelUploadConfig parallelUploadConfig =
        ParallelUploadConfig.newBuilder().setBucketName(bucketName).build();
    List<UploadResult> results =
        transferManager.uploadFiles(files, parallelUploadConfig).getUploadResults();
    for (UploadResult result : results) {
      System.out.println(
          "Upload for "
              + result.getInput().getName()
              + " completed with status "
              + result.getStatus());
    }
  }
}

Node.js

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud StorageNode.js.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

La biblioteca cliente de Node.js no admite cargas compuestas paralelas. En su lugar, usa cargas multiparte de la API de XML.

Python

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Python.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

La biblioteca cliente de Python no admite cargas compuestas paralelas. En su lugar, usa cargas multiparte de la API de XML.

API de REST

API de JSON

La API de JSON admite que subas fragmentos de objetos en paralelo y los vuelvas a combinar en un solo objeto usando la compose operación.

Ten en cuenta lo siguiente cuando diseñes código para cargas compuestas paralelas:

• Cuando se usa la operación compose, puedes borrar de forma definitiva los objetos de origen como parte del proceso de composición. Usa esta opción para minimizar la facturación de los objetos temporales que no necesitan protección con la eliminación no definitiva o el control de versiones de objetos.

• Para estar protegidos de los cambios a los objetos de origen entre las solicitudes de carga y de composición, debes proporcionar un número de generación esperado para cada origen.

API de XML

La API de XML admite que subas fragmentos de objetos en paralelo y los vuelvas a combinar en un solo objeto usando la compose operación.

Ten en cuenta lo siguiente cuando diseñes código para cargas compuestas paralelas:

• Cuando se usa la operación compose, los objetos de origen no se ven afectados por el proceso de composición.

  Esto significa que, si están destinados a ser temporales, debes borrarlos de forma explícita una vez que hayas completado con éxito la composición. Si no lo haces, los objetos de origen permanecerán en el bucket y se facturarán en consecuencia.

• Para estar protegidos de los cambios a los objetos de origen entre las solicitudes de carga y de composición, debes proporcionar un número de generación esperado para cada origen.

Soluciona problemas

En esta sección, se proporciona información para solucionar problemas de errores de gcloud CLI que pueden ocurrir con cargas compuestas paralelas.

No se puede verificar si el bucket de destino es compatible con las cargas compuestas paralelas

Problema: Cuando subes un archivo de 150 MiB o más con gcloud storage cp o gcloud storage mv, el comando registra el siguiente mensaje una vez, pero la carga se completa correctamente con el código de salida 0:

ERROR: Cannot check if the destination bucket is compatible for running
parallel composite uploads as the user does not permission to perform GET
operation on the bucket. The operation will be performed without parallel
composite upload feature and hence might perform relatively slower.

Solución: La gcloud CLI intenta ejecutar la verificación de compatibilidad de carga compuesta paralela. La principal no tiene el permiso storage.buckets.get en el bucket de destino, por lo que se rechaza la solicitud de los metadatos del bucket. Gcloud CLI controla el error de forma interna y no muestra un código de estado HTTP. En su lugar, registra el mensaje y vuelve a una carga normal.

Si deseas cargas compuestas paralelas, asegúrate de que la principal tenga los permisos storage.buckets.get, storage.objects.get y storage.objects.delete en el bucket de destino. Estos permisos se pueden otorgar a través del rol de administrador de almacenamiento (roles/storage.admin). Como alternativa, si la principal ya tiene los permisos storage.objects.get y storage.objects.delete a través de un rol como el de usuario de objetos de almacenamiento (roles/storage.objectUser), puede establecer la propiedad storage/parallel_composite_upload_compatibility_check en False para inhabilitar la verificación de compatibilidad.

403: does not have storage.objects.get access

Problema: Las cargas de archivos de menos de 150 MiB se realizan correctamente, pero las cargas de archivos de 150 MiB o más fallan con el código de salida 1 y un error similar al siguiente:

HTTPError 403: PRINCIPAL does not have storage.objects.get access to
the Google Cloud Storage object.

Solución: storage/parallel_composite_upload_compatibility_check está configurado en False y storage/parallel_composite_upload_enabled está configurado en None o True. En esta configuración, gcloud CLI omite la verificación de compatibilidad del bucket y continúa directamente con una carga compuesta paralela.

Los objetos temporales se suben correctamente porque la principal tiene el permiso storage.objects.create. Sin embargo, para componer los objetos temporales en el objeto final, se requiere el permiso storage.objects.get, y para borrar los objetos temporales después, se requiere el permiso storage.objects.delete.

Para resolver este problema, elige una de las siguientes opciones:

• Si no necesitas cargas compuestas paralelas, inhabilítalas:

  gcloud config set storage/parallel_composite_upload_enabled False
  

  Todos los archivos se suben como cargas normales, y la principal solo necesita los permisos incluidos en el rol de creador de objetos de almacenamiento (roles/storage.objectCreator). Puedes dejar storage/parallel_composite_upload_compatibility_check en cualquier valor.

• Si necesitas cargas compuestas paralelas, otórgale a la principal los permisos storage.objects.get y storage.objects.delete en el bucket de destino. Estos permisos se pueden otorgar a través del rol de usuario de objetos de almacenamiento (roles/storage.objectUser).

Si la carga fallida dejó objetos temporales en tu bucket, bórralos. De forma predeterminada, los objetos temporales usan el prefijo gcloud/tmp/parallel_composite_uploads/see_gcloud_storage_cp_help_for_details. Para borrar los objetos temporales que resultaron de una carga fallida, necesitas el permiso storage.objects.delete.

Ten en cuenta que el gcloud storage rsync comando se comporta de manera diferente a gcloud storage cp y gcloud storage mv. Cuando el destino es una raíz de bucket, como gs://my-bucket, gcloud storage rsync siempre requiere el permiso storage.buckets.get para sincronizar con el bucket, independientemente de la configuración de carga compuesta paralela. Cuando el destino es un subdirectorio de bucket, como gs://my-bucket/dir/, gcloud storage rsync no requiere el permiso storage.buckets.get, siempre que la verificación de compatibilidad esté inhabilitada en la configuración de carga compuesta paralela. En este caso, gcloud storage rsync requiere el permiso storage.objects.get en lugar de storage.buckets.get.