Composing Objects

Go to concepts

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.

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.

Code samples

Java

For more information, see the Cloud Storage Java API reference documentation.

import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class ComposeObject {
  public static void composeObject(
      String bucketName,
      String firstObjectName,
      String secondObjectName,
      String targetObjectName,
      String projectId) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of the first GCS object to compose
    // String firstObjectName = "your-first-object-name";

    // The ID of the second GCS object to compose
    // String secondObjectName = "your-second-object-name";

    // The ID to give the new composite object
    // String targetObjectName = "new-composite-object-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();

    Storage.ComposeRequest composeRequest =
        Storage.ComposeRequest.newBuilder()
            // addSource takes varargs, so you can put as many objects here as you want, up to the
            // max of 32
            .addSource(firstObjectName, secondObjectName)
            .setTarget(BlobInfo.newBuilder(bucketName, targetObjectName).build())
            .build();

    Blob compositeObject = storage.compose(composeRequest);

    System.out.println(
        "New composite object "
            + compositeObject.getName()
            + " was created by combining "
            + firstObjectName
            + " and "
            + secondObjectName);
  }
}

C++

For more information, see the Cloud Storage C++ API reference documentation.

To compose an object using C++, use the ComposeObject() method.

C#

For more information, see the Cloud Storage C# API reference documentation.

You cannot currently compose objects using the C# client library.

Go

For more information, see the Cloud Storage Go API reference documentation.

To compose an object using Go, see the Composer reference documentation.

Node.js

For more information, see the Cloud Storage Node.js API reference documentation.

To compose an object using NodeJS, see the Bucket reference documentation.

PHP

For more information, see the Cloud Storage PHP API reference documentation.

To compose an object using PHP, see the Google\Cloud\Storage\Bucket reference documentation.

Python

For more information, see the Cloud Storage Python API reference documentation.

To compose an object using Python, see the compose reference documentation.

Ruby

For more information, see the Cloud Storage Ruby API reference documentation.

To compose an object using Ruby, see the Google::Cloud::Storage reference documentation.

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