Compose objects (original) (raw)

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.

To get the permissions that you need to compose objects, ask your administrator to grant you the Storage Object User (roles/storage.objectUser) IAM role on the bucket. This predefined role contains the permissions required to compose objects. To see the exact permissions that are required, expand the Required permissions section:

If you want to set a retention configuration for the object you compose, you'll also need the storage.objects.setRetention permission. To get this permission, ask your administrator to grant you the Storage Object Admin (roles/storage.objectAdmin) role instead of the Storage Object User (roles/storage.objectUser) role.

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

C++

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

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

C#

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

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Node.js

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

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

REST APIs

JSON API

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
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 andSOURCE_OBJECT_2 are the names of the source objects to use in the object composition.
   • COMPOSITE_OBJECT_CONTENT_TYPE is theContent-Type of the resulting composite object.
3. Use cURL to call the JSON API with aPOST Object request:
   curl -X POST --data-binary @JSON_FILE_NAME \
   -H "Authorization: Bearer $(gcloud auth print-access-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.
   • 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. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Create an XML file that contains the following information: SOURCE_OBJECT_1 SOURCE_OBJECT_2 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 aPUT Object request that includes the compose query string parameter:
   curl -X PUT --data-binary @XML_FILE_NAME \
   -H "Authorization: Bearer $(gcloud auth print-access-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.
   • COMPOSITE_OBJECT_CONTENT_TYPE is theContent-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.