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:
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:
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.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-08-18 UTC."],[],[],null,["# Composite objects\n\n[Create](/storage/docs/composing-objects)\n\nThis page describes composite objects, which you create from existing objects\nwithout transferring additional object data. Composite objects are useful for\nmaking [appends to an existing object](#appends), as well as for recreating\nobjects that you [uploaded as multiple components in parallel](/storage/docs/parallel-composite-uploads).\n\nCompose operation\n-----------------\n\nThe compose operation concatenates the data in a given sequence of source\nobjects to create a new object called a *composite object*. The source objects\nall must:\n\n- Have the same [storage class](/storage/docs/storage-classes).\n- Be stored in the same Cloud Storage bucket.\n\nWhen you perform a composition:\n\n- The source objects are unaffected.\n- You can use between 1 and 32 source objects.\n- Source objects can themselves be composite objects.\n\nThe composite object that results from a composition:\n\n- Has the same storage class as the source objects.\n- Does not change if the source objects are subsequently replaced or deleted.\n\nWhen using [`gcloud storage`](/sdk/gcloud/reference/storage) to perform object composition, the object that\nresults has a [`Content-Type`](/storage/docs/metadata#content-type) set to match the `Content-Type` of the first\nsource object.\n\nComposite object metadata\n-------------------------\n\nThere are several differences between the metadata of a composite object and\nthe metadata of other objects:\n\n- Composite objects *do not* have an MD5 hash metadata field.\n\n- The ETag value of a composite object is not based on an MD5 hash, and client\n code should make no assumptions about composite object ETags except that\n they change whenever the underlying object changes per the\n [IETF specification for HTTP/1.1](https://datatracker.ietf.org/doc/html/rfc7232#section-2.3).\n\n | **Caution:** Exercise caution when first using composite objects, since any clients expecting to find an MD5 digest within the ETag header may conclude that object data has been corrupted, which could trigger endless data retransmission attempts.\n- Each composite object has a *component count* metadata field, which counts the\n number of non-composite objects contained within the composite object.\n\n - If you rewrite a composite object to a different location or storage class, the result is a composite object with a component count of 1.\n\nIntegrity Checking Composite Objects\n------------------------------------\n\nCloud Storage uses [CRC32C](https://datatracker.ietf.org/doc/html/rfc4960#appendix-B) for integrity checking each\nsource object at upload time and for allowing the caller to perform an integrity\ncheck of the resulting composite object when it is downloaded. CRC32C is an\nerror detecting code that can be efficiently calculated from the CRC32C\nvalues of its components. Your application should use CRC32C as follows:\n\n- When uploading source objects, you should calculate the CRC32C for each object using a CRC32C library, such as one of those listed in the [Object metadata page](/storage/docs/metadata#crc32c), and include that value in your request. Based on the values you provide, Cloud Storage [validates each upload](/storage/docs/data-validation).\n- The compose operation automatically checks that the source objects are correctly assembled, and it ignores any CRC32C value you provide as part of the compose request. A CRC32C of the resulting composite object is returned in the response.\n- If your application could change source objects between the time of uploading and composing those objects, you should specify generation-specific names for the source objects to avoid race conditions. Alternatively, you can build a CRC32C value from the CRC32C values of the intended source objects and compare it to the CRC32C value returned by the compose operation.\n- At download time, you should calculate the CRC32C of the downloaded object and compare that with the value included in the response.\n\n| **Note:** CRC32C is not intended to protect against [\"man-in-the-middle\"](https://en.wikipedia.org/wiki/Man-in-the-middle_attack) attacks, where someone modifies the content in a way that still matches the provided checksum. Protection against such attacks is provided by using SSL connections when uploading and downloading objects, which is the default for many tools and libraries, such as the Google Cloud CLI.\n\nLimited Append and Edit\n-----------------------\n\nYou can use the compose operation to perform limited object appends and edits.\n\nYou accomplish appending by uploading data to a temporary new object, composing\nthe object you wish to append with this temporary object, optionally naming the\noutput of the compose operation the same as the original object, and deleting\nthe temporary object.\n\nFor example, in the [gcloud CLI](/sdk/gcloud), the series of commands to\nappend the string `new data` to an existing Cloud Storage object is\nthe following: \n\n```\n$ echo 'new data' | gcloud storage cp - gs://bucket/temporary_object\n$ gcloud storage objects compose gs://bucket/object_to_append gs://bucket/temporary_object \\\n gs://bucket/object_to_append\n$ gcloud storage rm gs://bucket/temporary_object\n```\n\nYou can also use composition to support a basic flavor of object editing.\nFor example, you could compose an object *X* from the sequence *{Y1, Y2, Y3}* ,\nreplace the contents of *Y2* , and recompose *X* from those same components.\nNote that this requires that *Y1* , *Y2* , and *Y3* be left undeleted, so you\nwill be billed for those components as well as for the composite.\n| **Caution:** Compose operations create a new version of an object. When performing appends in a bucket with [Object Versioning](/storage/docs/object-versioning) enabled, be sure that you properly manage the noncurrent version of the object that each append generates.\n\nWhat's next\n-----------\n\n- [Compose an object](/storage/docs/composing-objects).\n- Learn about [parallel composite uploads](/storage/docs/parallel-composite-uploads).\n- Learn about [Multipart uploads](/storage/docs/multipart-uploads), an alternative way to upload objects in multiple chunks for XML API users."]]
