Cargas compuestas paralelas

Las cargas compuestas paralelas pueden ayudarte a subir archivos grandes de forma mucho más rápida cuando la velocidad de la red y del disco no son factores limitantes. En una carga compuesta en paralelo, un archivo se divide en hasta 32 fragmentos, los fragmentos se suben en paralelo a objetos temporales, el objeto final se vuelve a crear con los objetos temporales y los objetos temporales se borran.

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

Consideraciones

El objeto final que una carga compuesta paralela almacena en tu 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 elementos 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.

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 de bucket con cargas compuestas paralelas. Si no puedes obtener el rol de administrador de Storage (roles/storage.admin), puedes realizar cargas compuestas en paralelo con 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 a través de roles personalizados o cualquier otro rol predefinido.

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

Cómo las herramientas y las API 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 consola de Google Cloud no realiza cargas compuestas paralelas.

Línea de comandos

Las siguientes propiedades funcionan en conjunto para determinar cómo y cuándo la 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: Es la propiedad para activar o desactivar las verificaciones a nivel del bucket de compatibilidad y seguridad con las 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. La gcloud CLI solo realiza cargas compuestas paralelas cuando se cumplen todas las condiciones siguientes:

    El parámetro de configuración predeterminado es True. Si es False, gcloud CLI no realiza la verificación de compatibilidad.

    Establecer storage/parallel_composite_upload_compatibility_check en False no inhabilita 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, 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 marca --configuration 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 Storage Node.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 con la operación compose.

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

  • Cuando usas 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 ni 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 con la operación compose.

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 incluye información para solucionar los errores de gcloud CLI que pueden ocurrir con las 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: gcloud CLI intenta ejecutar la verificación de compatibilidad de la 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 recurre a una carga normal.

Si quieres realizar 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 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 se establece en False y storage/parallel_composite_upload_enabled se establece 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 Storage (roles/storage.objectCreator). Puedes dejar storage/parallel_composite_upload_compatibility_check en cualquier valor.

  • Si necesitas cargas compuestas paralelas, otorga 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 se generaron a partir de una carga con errores, necesitas el permiso storage.objects.delete.

Ten en cuenta que el comando gcloud storage rsync se comporta de manera diferente que 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 y cuando 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.