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 objeto composto. Todos os objetos de origem precisam:

Ao executar uma composição:

  • Os objetos de origem não são afetados.
  • É possível usar entre 1 e 32 objetos de origem.
  • Os próprios objetos de origem podem ser objetos compostos.

Objeto composto que resulta de uma composição:

  • tem a mesma classe de armazenamento que os objetos de origem;
  • não muda se os objetos de origem são substituídos ou excluídos posteriormente.

Ao usar a gcloud storage para realizar a composição do objeto, o objeto resultante 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:

  • Os objetos compostos não têm um campo de metadados de hash MD5.

  • O valor ETag de um objeto composto não é baseado em um hash MD5, e o código cliente não deve fazer suposições sobre ETags de objetos compostos, exceto que eles mudam sempre que o objeto subjacente é alterado pela especificação IETF para HTTP/1.1.

  • Cada objeto composto tem um campo de metadados de contagem de componentes, que conta o número de objetos não compostos contidos nele.

    • Se você reescrever um objeto composto para um local ou classe de armazenamento diferente, o resultado será um objeto composto com uma contagem de componentes igual a 1.

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.

Anexação e edição limitadas

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

Você anexa fazendo upload de dados para um objeto temporário novo, compondo o objeto que quer anexar com esse objeto temporário, nomeando opcionalmente a saída da operação de composição igual ao objeto original e excluindo o objeto temporário.

Por exemplo, na CLI gcloud, a série de comandos para anexar a string new data a um objeto atual do Cloud Storage é a seguinte:

$ echo 'new data' | gcloud storage cp - gs://bucket/temporary_object
$ gcloud storage objects compose gs://bucket/object_to_append gs://bucket/temporary_object \
    gs://bucket/object_to_append
$ gcloud storage rm gs://bucket/temporary_object

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

Durante uma operação de objeto de composição, o Cloud Storage mescla todos os contextos (prévia) dos objetos de origem e os anexa ao objeto de destino. Os contextos são mesclados para processar chaves de contexto exclusivas e duplicadas, conforme descrito nas seções a seguir.

Chaves de contexto exclusivas

Se os objetos de origem tiverem chaves de contexto exclusivas, o Cloud Storage 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 terá 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 processado pelo Cloud Storage substitui os valores de objetos processados anteriormente.

Por exemplo, considere objetos de origem processados na seguinte ordem:

  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 depois do 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