Objetos compuestos

Crear

En esta página, se describen objetos compuestos, que creaste a partir de objetos existentes sin transferir datos de objetos adicionales. Los objetos compuestos son útiles con el fin de agregar adjuntos a un objeto existente y volver a crear objetos que subiste como varios componentes en paralelo.

Operación de composición

La operación de composición concatena los datos de una secuencia determinada de objetos de origen para crear un objeto nuevo llamado objeto compuesto. Los objetos de origen deben cumplir con los siguientes requisitos:

  • Todos los objetos de origen deben tener la misma clase de almacenamiento.
  • Todos los objetos de origen deben estar almacenados en el mismo bucket de Cloud Storage.

Cuando realizas una composición, ten en cuenta lo siguiente:

  • De manera opcional, 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 objetos temporales que no necesitan protección mediante el borrado no definitivo o el control de versiones de objetos.
  • Puedes componer entre 1 y 32 objetos de origen.
  • Los objetos de origen pueden ser objetos compuestos.

El objeto compuesto que resulta de una composición tiene estas características:

  • El objeto compuesto tiene la misma clase de almacenamiento que los objetos de origen.
  • El objeto compuesto no cambia si los objetos de origen se reemplazan o borran más tarde.

Cuando se usa gcloud storage para realizar la composición del objeto, el objeto que resulta tiene un Content-Type configurado para que coincida con el Content-Type del primer objeto de origen.

Metadatos de objetos compuestos

Existen varias diferencias entre los metadatos de un objeto compuesto y los metadatos de otros objetos:

  • Los objetos compuestos no tienen un campo de metadatos hash MD5.

    • Se ignora cualquier valor MD5 que proporciones como parte de una solicitud de composición.

  • El valor ETag de un objeto compuesto no se basa en un hash MD5, y el código del cliente no debe hacer suposiciones sobre los ETag de objeto compuesto, excepto que cambian cada vez que el objeto subyacente cambia en la especificación IETF para HTTP/1.1.

  • Cada objeto compuesto tiene un campo de metadatos de recuento de componentes, que cuenta la cantidad de objetos no compuestos que contiene el objeto compuesto.

    • Si reescribes un objeto compuesto en una ubicación o clase de almacenamiento diferente, el resultado será un objeto compuesto con un recuento de componentes de 1.

Verificación de integridad de los objetos compuestos

Cloud Storage usa CRC32C para verificar la integridad de cada objeto de origen en el momento de carga y a fin de permitir que el emisor realice una verificación de integridad del objeto compuesto resultante cuando se descarga. CRC32C es un código de detección de error que se puede calcular con eficiencia a partir de los valores CRC32C de sus componentes. Tu aplicación debería usar CRC32C de la siguiente manera:

  • Cuando subes objetos de origen, deberías calcular el CRC32C de cada objeto con una biblioteca CRC32C, como alguno de los que se enumeran en la página de metadatos de objetos e incluir ese valor en tu solicitud. Según los valores que proporciones, Cloud Storage valida cada carga.
  • La operación de composición verifica de forma automática que los objetos de origen se ensamblen de forma correcta e ignora cualquier valor CRC32C que proporciones como parte del requisito de composición. Se muestra un valor CRC32C del objeto compuesto resultante en la respuesta.
  • Si tu aplicación puede cambiar los objetos de origen entre el momento de la carga y la composición de esos objetos, tendrás que especificar los nombres específicos de generación de los objetos de origen a fin de evitar condiciones de carrera. Como alternativa, puedes compilar un valor CRC32C a partir de los valores CRC32C de los objetos de origen deseados y compararlo con el valor CRC32C que muestra la operación de composición.
  • En el momento de la descarga, tienes que calcular el CRC32C del objeto descargado y compararlo con el valor incluido en la respuesta.

Agregar y editar

Puedes usar la operación de composición para realizar ediciones y agregados de objetos.

Para agregar datos a un objeto existente, primero debes crear un objeto temporal que contenga los datos que deseas agregar. Luego, redacta el objeto existente con el objeto temporal. Como parte del proceso de composición, puedes borrar el objeto temporal y la versión anterior del objeto original. También puedes nombrar el objeto resultante de la misma manera que el objeto original.

Por ejemplo, en la gcloud CLI, los siguientes comandos agregan la cadena new data a un objeto existente:

$ echo 'new data' | gcloud storage cp - gs://bucket/temporary_object
$ gcloud storage objects compose gs://bucket/existing_object gs://bucket/temporary_object \
    gs://bucket/existing_object --delete-source-objects

También puedes usar la composición para que sea compatible con una variante básica de edición de objetos. Por ejemplo, puedes componer un objeto X de la secuencia {Y1, Y2, Y3}, reemplazar el contenido de Y2 y recomponer X de esos mismos componentes. Ten en cuenta que esto requiere que no se borren Y1, Y2 ni Y3, por lo que se te facturará por esos componentes y por el compuesto.

Contextos de objetos compuestos

Cuando usas la operación de composición, Cloud Storage combina todos los contextos de los objetos de origen y los adjunta al objeto de destino. Este proceso controla las claves de contexto únicas y duplicadas, como se describe en las siguientes secciones.

Este comportamiento de combinación es el predeterminado. Se produce cuando no especificas contextos para el objeto de destino en la solicitud de composición. Puedes anular este comportamiento predeterminado borrando contextos o especificando contextos nuevos para el objeto de destino durante la operación de composición.

Claves de contexto únicas

Si los objetos de origen tienen claves de contexto únicas, Cloud Storage adjunta directamente estas claves y sus valores correspondientes al objeto de destino.

Considera el siguiente ejemplo:

Contextos del objeto de origen A: Department: Engineering, Status: Active

Contextos del objeto de origen B: Owner: m_jones, Version: 1.1

Después de la operación de composición, el objeto de destino tiene los siguientes contextos combinados:

  {
    "contexts": {
      "custom": {
        "Department": {
          "value": "Engineering",
          "createTime": "2023-10-26T10:00:00.000Z",
          "updateTime": "2023-10-26T10:00:00.000Z"
        },
        "Status": {
          "value": "Active",
          "createTime": "2023-10-26T10:00:00.000Z",
          "updateTime": "2023-10-26T10:00:00.000Z"
        },
        "Owner": {
          "value": "m_jones",
          "createTime": "2023-10-26T10:00:00.000Z",
          "updateTime": "2023-10-26T10:00:00.000Z"
        },
        "Version": {
          "value": "1.1",
          "createTime": "2023-10-26T10:00:00.000Z",
          "updateTime": "2023-10-26T10:00:00.000Z"
        }
      }
    }
  }

Claves de contexto duplicadas

Cuando varios objetos de origen tienen la misma clave de contexto, se usa el valor del último objeto de origen en la lista de composición que contiene esa clave para el objeto compuesto.

Por ejemplo, considera los objetos de origen procesados en el siguiente orden:

  1. Objeto de origen A

  2. Objeto de origen B

Contextos del objeto de origen A: Version: 1.0, ReleaseDate: 2024-01-15

Contextos del objeto de origen B: Version: 1.1, Owner: m_jones

Ambos objetos de origen tienen una clave Version, pero el objeto A tiene Version: 1.0 y el objeto B tiene Version: 1.1. Debido a que Cloud Storage procesa el objeto de origen B después del objeto de origen A, el valor Version del objeto de origen B tiene prioridad y el valor final es 1.1.

El objeto de destino combina estos contextos de la siguiente manera:

  {
    "contexts": {
      "custom": {
        "Version": {
          "value": "1.1",
          "createTime": "2025-01-01T00:00:00.000Z",
          "updateTime": "2025-01-01T00:00:00.000Z"
        },
        "ReleaseDate": {
          "value": "2024-01-15",
          "createTime": "2025-01-01T00:00:00.000Z",
          "updateTime": "2025-01-01T00:00:00.000Z"
        },
        "Owner": {
          "value": "m_jones",
          "createTime": "2025-01-01T00:00:00.000Z",
          "updateTime": "2025-01-01T00:00:00.000Z"
        }
      }
    }
  }

¿Qué sigue?