This page shows you how to compose Cloud Storage objects into a single object. A compose request takes between 1 and 32 objects and creates a new, composite object. The composite object is a concatenation of the source objects in the order they were specified in the request.
Note the following when composing objects:
- 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.
- Because other storage classes are subject to early deletion fees, you should always use Standard storage for temporary objects.
Required permissions
Console
The Google Cloud console does not support performing object compositions. Instead, use the Google Cloud CLI.
Command line
In order to complete this guide using a command-line utility, you must have the proper IAM permissions. If the buckets you want to access exist in a project that you did not create, you might need the project owner to give you a role that contains the necessary permissions.
For a list of permissions required for specific actions, see
IAM
permissions for gcloud storage
commands.
For a list of relevant roles, see Cloud Storage roles. Alternatively, you can create a custom role that has specific, limited permissions.
Client libraries
In order to complete this guide using the Cloud Storage client libraries, you must have the proper IAM permissions. If the buckets you want to access exist in a project that you did not create, you might need the project owner to give you a role that contains the necessary permissions.
Unless otherwise noted, client library requests are made through the JSON API and require permissions as listed in IAM permissions for JSON methods. To see which JSON API methods are invoked when you make requests using a client library, log the raw requests.
For a list of relevant IAM roles, see Cloud Storage roles. Alternatively, you can create a custom role that has specific, limited permissions.
REST APIs
JSON API
In order to complete this guide using the JSON API, you must have the proper IAM permissions. If the buckets you want to access exist in a project that you did not create, you might need the project owner to give you a role that contains the necessary permissions.
For a list of permissions required for specific actions, see IAM permissions for JSON methods.
For a list of relevant roles, see Cloud Storage roles. Alternatively, you can create a custom role that has specific, limited permissions.
Create a composite object
Console
The Google Cloud console does not support performing object compositions. Instead, use the Google Cloud CLI.
Command line
Use the gcloud storage objects compose
command:
gcloud storage objects 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
andSOURCE_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.
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage C# API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Java API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Node.js API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage PHP API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Python API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
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
andSOURCE_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.
Use
cURL
to call the JSON API with aPOST
Object request:curl -X POST --data-binary @JSON_FILE_NAME \ -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
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
Create an 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
andSOURCE_OBJECT_2
are the names of the source objects to use in the object composition.
Use
cURL
to call the XML API with aPUT
Object request andcompose
query string parameter:curl -X PUT --data-binary @XML_FILE_NAME \ -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
- Learn more about object composition.
- Learn how to use request preconditions to prevent race conditions.