Composing Objects

This page shows you how to compose source objects to create a composite object. You can compose up to 32 source objects in a single request. For general information about object composition, see Composite objects.

Important: The source objects are unaffected by the composition process. If they are meant to be temporary, you must delete them once you've successfully completed the composition.

To create a composite object:

Console

The Cloud Console does not support performing object compositions. Use gsutil instead.

gsutil

Use the gsutil compose command:

gsutil compose gs://[BUCKET_NAME]/[SOURCE_OBJECT_1] gs://[BUCKET_NAME]/[SOURCE_OBJECT_2] gs://[BUCKET_NAME]/[COMPOSITE_OBJECT_NAME]

Where:

• [BUCKET_NAME] is the name of the bucket that contains the source objects.
• [SOURCE_OBJECT_1] and [SOURCE_OBJECT_2] are the names of the source objects to use in the object composition.
• [COMPOSITE_OBJECT_NAME] is the name you are giving to the result of the object composition.

Note: You can also use a wildcard to compose objects with a common prefix without having to list each object separately in the compose command.

REST APIs

JSON API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Create a .json file that contains the following information:

   {
     "sourceObjects": [
       {
         "name": "[SOURCE_OBJECT_1]"
       },
       {
         "name": "[SOURCE_OBJECT_2]"
       }
     ],
     "destination": {
       "contentType": "[COMPOSITE_OBJECT_CONTENT_TYPE]"
     }
   }

   Where:

   • [SOURCE_OBJECT_1] and [SOURCE_OBJECT_2] are the names of the source objects to use in the object composition.
   • [COMPOSITE_OBJECT_CONTENT_TYPE] is the Content-Type of the resulting composite object.

3. Use cURL to call the JSON API with a POST Object request:

   curl -X POST --data-binary @[JSON_FILE_NAME].json \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     -H "Content-Type: application/json" \
     "https://storage.googleapis.com/storage/v1/b/[BUCKET_NAME]/o/[COMPOSITE_OBJECT_NAME]/compose"

   Where:

   • [JSON_FILE_NAME] is the name of the file you created in the previous step.
   • [OAUTH2_TOKEN] is the access token you generated earlier in the guide.
   • [BUCKET_NAME] is the name of the bucket that contains the source objects.
   • [COMPOSITE_OBJECT_NAME] is the name you are giving to the result of the object composition.

If successful, the response is an object resource for the resulting composite object.

XML API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Create a .xml file that contains the following information:

     <ComposeRequest>
       <Component>
         <Name>[SOURCE_OBJECT_1]</Name>
       </Component>
       <Component>
         <Name>[SOURCE_OBJECT_2]</Name>
       </Component>
     </ComposeRequest>

   Where:

   • [SOURCE_OBJECT_1] and [SOURCE_OBJECT_2] are the names of the source objects to use in the object composition.

3. Use cURL to call the XML API with a PUT Object request and compose query string parameter:

   curl -X PUT --data-binary @[XML_FILE_NAME].xml \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     -H "Content-Type: [COMPOSITE_OBJECT_CONTENT_TYPE]" \
     "https://storage.googleapis.com/[BUCKET_NAME]/[COMPOSITE_OBJECT_NAME]?compose"

   Where:

   • [XML_FILE_NAME] is the name of the file you created in the previous step.
   • [OAUTH2_TOKEN] is the access token you generated earlier in the guide.
   • [COMPOSITE_OBJECT_CONTENT_TYPE] is the Content-Type of the resulting composite object.
   • [BUCKET_NAME] is the name of the bucket that contains the source objects.
   • [COMPOSITE_OBJECT_NAME] is the name you are giving to the result of the object composition.

If successful, an empty response body is returned.

Note: The XML API supports including a generation number for each <Component>, using either a <Generation> element or an <IfGenerationMatch> element.

What's next

• Learn more about object composition.
• View object metadata to get the component count of a composite object.