Compose an Object

The compose operation creates a new object whose contents are the concatenation of a given sequence of up to 32 component objects under the same bucket. The components are unaffected by the process, and the resulting composite does not change if its components are replaced or deleted.

Composite objects may even be built from other existing composites, provided that the total component count does not exceed 1024. There is a per-project rate limit on how many components you can compose of approximately 200 per second. This rate counts both the components being appended to a composite object as well as the components being copied when the composite object of which they are a part is copied.

For more information, see Composite Objects.

Query string parameters

Parameter Description Required
compose Issues a compose request. Requires a ComposeRequest XML document in the request body. No
Expires Used for Signed URLs. No
GoogleAccessId Used for Signed URLs. No
Signature Used for Signed URLs. No

Request headers

In addition to common request headers, the following can be used.

Header Description Required
Content-Encoding The compression algorithm that was used to compress the object you are uploading. No
Content-Disposition A header you can set on an object that specifies presentational information about how the object data is to be transmitted. No
x-goog-acl The predefined ACL that you want to apply to the bucket. Do not use if you are using the acl query string parameter to apply ACLs. No
x-goog-metadata-directive The instructions for handling metadata during a copy operation. Can be COPY or REPLACE. The default value is COPY. No
x-goog-meta- An extension header that can be used to store additional metadata that is not provided by the other fields. No

To compose objects encrypted by a customer-supplied encryption key, use the headers listed on the Encryption page in your request.

Request body elements

The following request body elements are applicable only if you use the compose query string parameter to issue a compose request.

Element Description
ComposeRequest Container for a compose request.
Component Container for a compose request component argument.
Name Object name for a compose request component.
Generation Generation number for a compose request component.
IfGenerationMatch Expected current generation number for a compose request component. The request will fail if the component object has a different generation.

Request syntax

PUT /<object>?compose HTTP/1.1
Host: <bucket>.storage.googleapis.com
Date: <date>
Content-Length: <request body length>
Authorization: <authentication string>

<ComposeRequest>
  <Component>
    <Name>component-obj-1</Name>
  </Component>
  <Component>
    <Name>component-obj-2</Name>
    <Generation>1361471441094000</Generation>
  </Component>
  <Component>
    <Name>component-obj-3</Name>
    <IfGenerationMatch>1361471441094000</IfGenerationMatch>
  </Component>
</ComposeRequest>

Response headers

The request can return a variety of response headers depending on the request headers you use.

Response body elements

The response does not include an XML document in the response body.

Send feedback about...

Cloud Storage Documentation