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 roles
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 permissionssection:
Required permissions
-
storage.objects.create
-
storage.objects.delete
- This permission is only required if you want to give the object you compose the same name as an object that already exists in the bucket.
-
storage.objects.get
-
storage.objects.list
- This permission is only required if you want to use wildcards to compose objects with a common prefix without having to list each object separately in your Google Cloud CLI command.
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.
You can also get these permissions with other predefined roles or custom roles .
For information about granting roles on buckets, see Use IAM with buckets .
Create a composite object
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 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 .
C#
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 .
Go
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 .
Java
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 .
Node.js
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 .
PHP
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 .
Python
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 .
Ruby
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 .