Composing Objects

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

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.

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.

What's next