Objetos compostos

Criar

Esta página descreve objetos compostos que você cria a partir de objetos existentes sem transferir dados de objetos adicionais. Objetos compostos são úteis para criar anexos em um objeto atual, bem como recriar objetos que você fez o upload como vários componentes em paralelo.

Operação de composição

A operação de composição concatena os dados em uma determinada sequência de objetos de origem para criar um novo objeto chamado elemento composto. Os objetos de origem precisam atender a estes requisitos:

  • Todos os objetos de origem precisam ter a mesma classe de armazenamento.
  • Todos os objetos de origem precisam ser armazenados no mesmo bucket do Cloud Storage.

Ao executar uma composição, observe o seguinte:

  • Opcionalmente, é possível excluir os objetos de origem como parte do processo de composição. Use essa opção para minimizar o faturamento de objetos temporários que não precisam ser protegidos pela exclusão reversível ou pelo controle de versões de objetos.
  • É possível compor entre 1 e 32 objetos de origem.
  • Os próprios objetos de origem podem ser objetos compostos.

O objeto composto resultante de uma composição tem estas características:

  • O objeto composto tem a mesma classe de armazenamento que os objetos de origem.
  • O objeto composto não muda se os objetos de origem forem substituídos ou excluídos posteriormente.

Ao usar gcloud storage para realizar a composição do objeto, o objeto que resulta tem um Content-Type definido para corresponder ao Content-Type do primeiro objeto de origem.

Metadados do objeto composto

Há várias diferenças entre os metadados de um objeto composto e aqueles de outros objetos:

Como fazer verificação de integridade de objetos compostos

O Cloud Storage usa o CRC32C para verificar a integridade de cada objeto de origem no momento do upload e para permitir que o autor da chamada execute uma verificação de integridade do objeto composto resultante quando o download dele é feito. O CRC32C é um código de detecção de erros que pode ser calculado com eficiência a partir dos valores CRC32C dos componentes dele. O aplicativo usará o CRC32C da maneira a seguir:

  • Ao fazer upload de objetos de origem, calcule o CRC32C de cada objeto usando uma biblioteca de CRC32C, como uma das listadas na página de metadados do objeto, e inclua esse valor na solicitação. Com base nos valores inseridos, o Cloud Storage valida cada upload.
  • A operação de composição verifica automaticamente se os objetos de origem estão montados corretamente e ignora todos os valores CRC32C fornecidos como parte da solicitação de composição. Uma CRC32C do objeto composto resultante é retornada na resposta.
  • Se o aplicativo puder alterar objetos de origem entre o momento de fazer o upload e compor esses objetos, defina nomes específicos de geração para os objetos de origem para evitar disputas. Como alternativa, é possível criar um valor CRC32C com base nos valores CRC32C dos objetos de origem pretendidos e compará-lo ao valor CRC32C retornado pela operação de composição.
  • No momento do download, calcule o CRC32C do objeto baixado e o compare com o valor incluído na resposta.

Adicionar ao final e editar

É possível usar a operação de composição para executar edições e anexos de objetos.

Para anexar dados a um objeto atual, primeiro crie um objeto temporário que contenha os dados que você quer anexar. Em seguida, componha o objeto atual com o objeto temporário. Como parte do processo de composição, é possível excluir o objeto temporário e a versão anterior do objeto original. Também é possível nomear o objeto resultante da mesma forma que o objeto original.

Por exemplo, na CLI gcloud, os comandos abaixo adicionam ao final a string new data a um objeto atual:

$ 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

Você também pode usar composição para dar suporte a uma versão básica de edição de objetos. Por exemplo, é possível compor um objeto X com a sequência {Y1, Y2, Y3}, substituir o conteúdo de Y2 e recompor X a partir desses mesmos componentes. Isso exige que Y1, Y2 e Y3 não sejam excluídos, por isso você será cobrado por esses componentes e pelo objeto composto como um todo.

Contextos de objetos compostos

Ao usar a operação de composição compose operation, o Cloud Storage mescla todos os contexts dos objetos de origem e os anexa ao objeto de destino. Esse processo processa chaves de contexto exclusivas e duplicadas, conforme descrito nas seções a seguir.

Esse comportamento de mesclagem é o padrão. Ele ocorre quando você não especifica contextos para o objeto de destino na solicitação de composição. É possível substituir esse comportamento padrão limpando os contextos ou especificando novos contextos para o objeto de destino durante a operação de composição.

Chaves de contexto exclusivas

Se os objetos de origem tiverem chaves de contexto exclusivas, o Cloud Storage vai anexar diretamente essas chaves e os valores correspondentes ao objeto de destino.

Veja o exemplo a seguir.

Contextos do objeto de origem A: Department: Engineering, Status: Active

Contextos do objeto de origem B: Owner: m_jones, Version: 1.1

Após a operação de composição, o objeto de destino tem os seguintes 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"
        }
      }
    }
  }

Chaves de contexto duplicadas

Quando vários objetos de origem têm a mesma chave de contexto, o valor do último objeto de origem na lista de composição que contém essa chave é usado para o objeto composto.

Por exemplo, considere objetos de origem processados na ordem a seguir:

  1. Objeto de origem A

  2. Objeto de origem B

Contextos do objeto de origem A: Version: 1.0, ReleaseDate: 2024-01-15

Contextos do objeto de origem B: Version: 1.1, Owner: m_jones

Os dois objetos de origem têm uma chave Version, mas o objeto A tem Version: 1.0 e o objeto B tem Version: 1.1. Como o Cloud Storage processa o objeto de origem B após o objeto de origem A, o valor Version do objeto de origem B tem precedência e o valor final é 1.1.

O objeto de destino combina esses contextos da seguinte maneira:

  {
    "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"
        }
      }
    }
  }

A seguir