Console
    Start free

    Use object contexts

    This page describes how to attach and manage contexts on Cloud Storage objects in the form of key-value pairs.

    Get the required roles

    To get the permissions that you need to create and manage object contexts, ask your administrator to grant you the following IAM roles on the object:

    For more information about granting roles, see Manage access to projects, folders, and organizations .

    These predefined roles contain the permissions required to create and manage object contexts. To see the exact permissions that are required, expand the Required permissionssection:

    Required permissions

    The following permissions are required to create and manage object contexts:

    • Create an object with object contexts:
      • storage.objects.create
      • storage.objects.createContext
    • Attach, update, and delete object contexts:
      • storage.objects.update
      • storage.objects.createContext
      • storage.objects.updateContext
      • storage.objects.deleteContext
    • Drop object contexts: storage.objects.dropContexts
    • View object contexts:
      • storage.objects.get
      • storage.objects.list

    You might also be able to get these permissions with custom roles or other predefined roles .

    Attach contexts to new objects

    Attach contexts to objects when you upload new objects to Cloud Storage buckets. Each context consists of a key and a value.

    Command line

    To attach contexts when you upload objects with the gcloud storage cp command, use the --custom-contexts flag:

    gcloud storage cp OBJECT_LOCATION 
gs:// DESTINATION_BUCKET_NAME 
--custom-contexts= KEY 
= VALUE 
,...

    Where:

    • OBJECT_LOCATION is the local path to your object. For example, Desktop/employees.txt .
    • DESTINATION_BUCKET_NAME is the name of the bucket to which you are uploading your object. For example, my-bucket .
    • KEY is the context key to attach to an object. For example, Department . You can specify multiple key-value pairs separated by commas.
    • VALUE is the value to associate with the context key. For example, Human resources .

    Alternatively, create a JSON file that contains the contexts you want to attach to the objects, and use the --custom-contexts-file flag:

      
 { 
  
 " KEY 
" 
 : 
  
 { 
  
 "value" 
 : 
  
 " VALUE 
" 
  
 }, 
  
 ... 
  
 }

    Where:

    • KEY is the context key to attach to an object. For example, Department . You can specify multiple key-value pairs.
    • VALUE is the value to associate with the context key. For example, Human resources .

    To attach contexts when you upload directories with the gcloud storage rsync command, use the --custom-contexts flag or the --custom-contexts-file flag:

    gcloud storage rsync DIRECTORY_LOCATION 
gs:// DESTINATION_BUCKET_NAME 
--recursive --custom-contexts= KEY 
= VALUE 
,...

    Where:

    • DIRECTORY_LOCATION is the local path to your directory. For example, ~/my_directory .
    • DESTINATION_BUCKET_NAME is the name of the bucket to which you are uploading your directory. For example, my-bucket .
    • KEY is the context key to attach to objects. For example, Department . You can specify multiple key-value pairs separated by commas.
    • VALUE is the value to associate with the context key. For example, Human resources .

    JSON API

    To attach contexts to objects when you upload new objects, use any of the following methods:

    As part of the object metadata in JSON format, include the contexts field:

      
 { 
  
 "contexts" 
 : 
  
 { 
  
 "custom" 
 : 
  
 { 
  
 " KEY 
" 
 : 
  
 { 
  
 "value" 
 : 
  
 " VALUE 
" 
  
 }, 
  
 ... 
  
 } 
  
 } 
  
 }

    Where:

    • KEY is the context key to attach to an object. For example, Department . You can specify multiple key-value pairs in the custom object.
    • VALUE is the value to associate with the context key. For example, Human resources .

    Attach or modify contexts to an existing object

    You can attach new contexts to your existing objects in the Cloud Storage buckets.

    Command line

    Use the gcloud storage objects update command:

    gcloud storage objects update gs:// BUCKET_NAME 
/ OBJECT_NAME 
 CUSTOM_CONTEXTS_FLAG

    Where:

    • BUCKET_NAME is the name of the bucket that contains the object for which you want to edit context. For example, my-bucket .
    • OBJECT_NAME is the name of the object. For example, employees.txt .

    • CUSTOM_CONTEXTS_FLAG is any of the following flags:

      • To replace all existing contexts, use --custom-contexts= KEY = VALUE ,... or --custom-contexts-file= CUSTOM_CONTEXTS_FILE

        Where:

        • KEY is the context key to attach to an object. For example, Department . You can specify multiple key-value pairs separated by commas.
        • VALUE is the value to associate with the context key. For example, Human resources .
        • CUSTOM_CONTEXTS_FILE is the path to the JSON or YAML file that contains the contexts you want to attach to the object.

      • To delete all existing contexts, use the --clear-custom-contexts flag.

      • To add, modify, or delete individual contexts, use a combination of --update-custom-contexts= KEY = VALUE ,... and --remove-custom-contexts= KEY ,...

        Where:

        • KEY is the context key that you want to attach to or delete from an object. For example, Department .
        • VALUE is the value to associate with the context key that you want to attach to or delete from an object. For example, Human resources .

    If successful, the response looks like the following example:

    Patching gs://my-bucket/employees.txt#1560574162144861...
  Completed 1

    Client libraries

    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 client libraries .

      import 
  
 com.google.cloud.storage. Blob 
 
 ; 
 import 
  
 com.google.cloud.storage. BlobId 
 
 ; 
 import 
  
 com.google.cloud.storage. BlobInfo 
 
 ; 
 import 
  
 com.google.cloud.storage. BlobInfo 
. ObjectContexts 
 
 ; 
 import 
  
 com.google.cloud.storage. BlobInfo 
. ObjectCustomContextPayload 
 
 ; 
 import 
  
 com.google.cloud.storage. Storage 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageOptions 
 
 ; 
 import 
  
 com.google.common.collect.Maps 
 ; 
 import 
  
 java.util.Map 
 ; 
 public 
  
 class 
 SetObjectContexts 
  
 { 
  
 public 
  
 static 
  
 void 
  
 setObjectContexts 
 ( 
  
 String 
  
 projectId 
 , 
  
 String 
  
 bucketName 
 , 
  
 String 
  
 objectName 
 , 
  
 String 
  
 key 
 , 
  
 String 
  
 value 
 ) 
  
 throws 
  
 Exception 
  
 { 
  
 // 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 your GCS object 
  
 // String objectName = "your-object-name"; 
  
 // The context key-value you want to add 
  
 // String key = "your-context-key"; 
  
 // String value = "your-context-value"; 
  
 try 
  
 ( 
  Storage 
 
  
 storage 
  
 = 
  
  StorageOptions 
 
 . 
 newBuilder 
 (). 
 setProjectId 
 ( 
 projectId 
 ). 
 build 
 (). 
  getService 
 
 ()) 
  
 { 
  
  BlobId 
 
  
 blobId 
  
 = 
  
  BlobId 
 
 . 
 of 
 ( 
 bucketName 
 , 
  
 objectName 
 ); 
  
  Blob 
 
  
 blob 
  
 = 
  
 storage 
 . 
 get 
 ( 
 blobId 
 ); 
  
 if 
  
 ( 
 blob 
  
 == 
  
 null 
 ) 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "The object " 
  
 + 
  
 objectName 
  
 + 
  
 " was not found in " 
  
 + 
  
 bucketName 
 ); 
  
 return 
 ; 
  
 } 
  
 // Recommended: Set a generation-match precondition to avoid potential race 
  
 // conditions and data corruptions. The request to update returns a 412 error if 
  
 // the object's generation number does not match your precondition. 
  
  Storage 
 
 . 
 BlobTargetOption 
  
 precondition 
  
 = 
  
  Storage 
 
 . 
 BlobTargetOption 
 . 
 generationMatch 
 (); 
  
 // This section demonstrates how to upsert, delete all, and delete a specific context. 
  
 // To upsert a context (if the key already exists, its value is replaced; 
  
 // otherwise, a new key-value pair is added): 
  
  ObjectCustomContextPayload 
 
  
 payload 
  
 = 
  
  ObjectCustomContextPayload 
 
 . 
 newBuilder 
 (). 
 setValue 
 ( 
 value 
 ). 
 build 
 (); 
  
 Map<String 
 , 
  
 ObjectCustomContextPayload 
>  
 custom 
  
 = 
  
 Maps 
 . 
 newHashMap 
 (); 
  
 custom 
 . 
 put 
 ( 
 key 
 , 
  
 payload 
 ); 
  
  ObjectContexts 
 
  
 contexts 
  
 = 
  
  ObjectContexts 
 
 . 
 newBuilder 
 (). 
  setCustom 
 
 ( 
 custom 
 ). 
 build 
 (); 
  
 /* 
 * To delete all existing contexts: 
 * ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(null).build(); 
 */ 
  
 /* 
 * To delete a specific key from the context: 
 * Map<String, ObjectCustomContextPayload> custom = Maps.newHashMap(); 
 * custom.put(key, null); 
 * ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(custom).build(); 
 */ 
  
  BlobInfo 
 
  
 pendingUpdate 
  
 = 
  
 blob 
 . 
  toBuilder 
 
 (). 
 setContexts 
 ( 
 contexts 
 ). 
 build 
 (); 
  
 storage 
 . 
 update 
 ( 
 pendingUpdate 
 , 
  
 precondition 
 ); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
  
 "Updated custom contexts for object " 
  
 + 
  
 objectName 
  
 + 
  
 " in bucket " 
  
 + 
  
 bucketName 
 ); 
  
 } 
  
 } 
 }

    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 settings for the object, which must include the contexts configuration fields for the object.

      To add, modify, or overwrite existing contexts, use the following format:

        
 { 
  
 "contexts" 
 : 
  
 { 
  
 "custom" 
 : 
  
 { 
  
 " KEY 
" 
 : 
  
 { 
  
 "value" 
 : 
  
 " VALUE 
" 
  
 }, 
  
 ... 
  
 } 
  
 } 
  
 }

      Where:

      • KEY is the context key to attach to an object. For example, Department . You can specify multiple key-value pairs in the custom object.
      • VALUE is the value to associate with the context key. For example, Human resources .

      To delete all existing contexts, use the following format:

        
 { 
  
 "contexts" 
 : 
  
 { 
  
 "custom" 
 : 
  
 null 
  
 } 
  
 }

      To delete a specific key from the context, use the following format:

        
 { 
  
 "contexts" 
 : 
  
 { 
  
 "custom" 
 : 
  
 { 
  
 " KEY 
" 
 : 
  
 null 
 , 
  
 ... 
  
 } 
  
 } 
  
 }

      Where:

      KEY is the context key that you want to delete from an object. For example, Department . You can specify multiple keys to delete from the custom object.

    3. Use cURL to call the JSON API with a PATCH Object request:

      curl -X PATCH --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/ OBJECT_NAME 
"

      Where:

      • JSON_FILE_NAME is the path to the file that includes the object contexts information.
      • BUCKET_NAME is the name of the bucket that contains the object for which you want to edit context. For example, my-bucket .
      • OBJECT_NAME is the URL-encoded name of the object. For example, employees.txt .

    Alternatively, you can replace an object's context with a PUT Object request. The PUT object request also replaces other object metadata. Therefore, we don't recommend using the PUT object request.

    View object contexts

    You can view an object's contexts by listing object metadata or describing a specific object.

    Command line

    Use the gcloud storage objects describe command:

    gcloud storage objects describe gs:// BUCKET_NAME 
/ OBJECT_NAME

    Where:

    • BUCKET_NAME is the name of the bucket containing the object whose context you want to view. For example, my-bucket .
    • OBJECT_NAME is the name of the object whose context you want to view. For example, employees.txt

    If successful, the response looks similar to the following example:

    bucket: my-bucket
contexts:
  Department:
    createTime: '2023-01-01T00:00:00.000000+00:00'
    type: CUSTOM
    updateTime: '2023-01-01T00:00:00.000000+00:00'
    value: Human resources
name: employees.txt

    Client libraries

    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 client libraries .

      import 
  
 com.google.cloud.storage. Blob 
 
 ; 
 import 
  
 com.google.cloud.storage. BlobInfo 
. ObjectContexts 
 
 ; 
 import 
  
 com.google.cloud.storage. BlobInfo 
. ObjectCustomContextPayload 
 
 ; 
 import 
  
 com.google.cloud.storage. Storage 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageOptions 
 
 ; 
 import 
  
 java.util.Map 
 ; 
 public 
  
 class 
 GetObjectContexts 
  
 { 
  
 public 
  
 static 
  
 void 
  
 getObjectContexts 
 ( 
 String 
  
 projectId 
 , 
  
 String 
  
 bucketName 
 , 
  
 String 
  
 objectName 
 ) 
  
 throws 
  
 Exception 
  
 { 
  
 // 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 your GCS object 
  
 // String objectName = "your-object-name"; 
  
 try 
  
 ( 
  Storage 
 
  
 storage 
  
 = 
  
  StorageOptions 
 
 . 
 newBuilder 
 (). 
 setProjectId 
 ( 
 projectId 
 ). 
 build 
 (). 
  getService 
 
 ()) 
  
 { 
  
  Blob 
 
  
 blob 
  
 = 
  
 storage 
 . 
 get 
 ( 
 bucketName 
 , 
  
 objectName 
 ); 
  
 if 
  
 ( 
 blob 
  
 == 
  
 null 
 ) 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "The object " 
  
 + 
  
 objectName 
  
 + 
  
 " was not found in " 
  
 + 
  
 bucketName 
 ); 
  
 return 
 ; 
  
 } 
  
  ObjectContexts 
 
  
 objectContexts 
  
 = 
  
 blob 
 . 
  getContexts 
 
 (); 
  
 if 
  
 ( 
 objectContexts 
  
 != 
  
 null 
 ) 
  
 { 
  
 Map<String 
 , 
  
 ObjectCustomContextPayload 
>  
 customContexts 
  
 = 
  
 objectContexts 
 . 
  getCustom 
 
 (); 
  
 if 
  
 ( 
 customContexts 
  
 == 
  
 null 
 ) 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "No custom contexts found for object: " 
  
 + 
  
 objectName 
 ); 
  
 return 
 ; 
  
 } 
  
 // Print blob's object contexts 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "\nCustom Contexts:" 
 ); 
  
 for 
  
 ( 
 Map 
 . 
 Entry<String 
 , 
  
 ObjectCustomContextPayload 
>  
 custom 
  
 : 
  
 customContexts 
 . 
 entrySet 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 custom 
 . 
 getKey 
 () 
  
 + 
  
 "=" 
  
 + 
  
 custom 
 . 
 getValue 
 ()); 
  
 } 
  
 } 
  
 } 
  
 } 
 }

    JSON API

    1. Have gcloud CLI installed and initialized , which lets you generate an access token for the Authorization header.

    2. Use cURL to call the JSON API with a GET Object request:

      curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/ BUCKET_NAME 
/o/ OBJECT_NAME 
"

      Where:

      • BUCKET_NAME is the name of the bucket containing the object whose context you want to view. For example, my-bucket .
      • OBJECT_NAME is the URL-encoded name of the object whose context you want to view. For example, employees.txt .

      If successful, the response looks similar to the following example:

        
 { 
  
 "kind" 
 : 
  
 "storage#object" 
 , 
  
 "name" 
 : 
  
 "employees.txt" 
 , 
  
 "bucket" 
 : 
  
 "my-bucket" 
 , 
  
 "contexts" 
 : 
  
 { 
  
 "custom" 
 : 
  
 { 
  
 "Department" 
 : 
  
 { 
  
 "value" 
 : 
  
 "Human resources" 
 , 
  
 "createTime" 
 : 
  
 "2023-01-01T00:00:00.000Z" 
 , 
  
 "updateTime" 
 : 
  
 "2023-01-01T00:00:00.000Z" 
  
 } 
  
 } 
  
 } 
  
 }

    Filter objects by contexts

    Filter objects by the existence of object context keys or their specific values. Filtering objects by contexts helps to locate and manage particular groups of objects efficiently. For details, see Filter objects by contexts .

    Manage object contexts during object operations

    By default, Cloud Storage preserves object contexts when you copy, rewrite, compose, move, or restore objects.

    Copy objects

    By default, Cloud Storage preserves object contexts from the source object during a copy operation, even if you override other metadata. To modify object contexts during a copy operation, complete the following steps:

    Command line

    The gcloud storage cp command, gcloud storage rsync command, and gcloud storage mv command preserve contexts from the source object by default. To modify contexts during these operations, use any of the following flags:

    • The --custom-contexts flag to set new contexts for the destination object.

    • The --clear-custom-contexts flag to prevent contexts from the source object from being attached to the destination object.

    • A combination of the --update-custom-contexts and --remove-custom-contexts flags to modify individual contexts from the source object before attaching them to the destination object.

    To set new contexts when you copy an object, use the gcloud storage cp command:

    gcloud storage cp gs:// SOURCE_BUCKET_NAME 
/ SOURCE_OBJECT_NAME 
gs:// DESTINATION_BUCKET_NAME 
/ DESTINATION_OBJECT_NAME 
--custom-contexts= KEY 
= VALUE 
,...

    Where:

    • SOURCE_BUCKET_NAME is the name of the bucket containing the object to copy. For example, my-source-bucket .
    • SOURCE_OBJECT_NAME is the name of the object to copy. For example, employees.txt .
    • DESTINATION_BUCKET_NAME is the name of the bucket to copy the object to. For example, my-destination-bucket .
    • DESTINATION_OBJECT_NAME is the name of the destination object. For example, employees-backup.txt .
    • KEY is the context key to attach to an object. For example, Department . You can specify multiple key-value pairs separated by commas.
    • VALUE is the value to associate with the context key. For example, Human resources .

    To remove all contexts from the source object when you copy an object, use the gcloud storage cp command:

    gcloud storage cp gs:// SOURCE_BUCKET_NAME 
/ SOURCE_OBJECT_NAME 
gs:// DESTINATION_BUCKET_NAME 
/ DESTINATION_OBJECT_NAME 
--clear-custom-contexts

    Where:

    • SOURCE_BUCKET_NAME is the name of the bucket containing the object to copy. For example, my-source-bucket .
    • SOURCE_OBJECT_NAME is the name of the object to copy. For example, pets/dog.png .
    • DESTINATION_BUCKET_NAME is the name of the bucket to copy the object to. For example, my-destination-bucket .
    • DESTINATION_OBJECT_NAME is the name of the destination object. For example, pets/cat.png .

    To modify individual contexts from the source object when you copy an object, use the gcloud storage cp command with --update-custom-contexts and --remove-custom-contexts :

    gcloud storage cp gs:// SOURCE_BUCKET_NAME 
/ SOURCE_OBJECT_NAME 
gs:// DESTINATION_BUCKET_NAME 
/ DESTINATION_OBJECT_NAME 
--update-custom-contexts= KEY 
= VALUE 
,... --remove-custom-contexts= KEY 
,...

    Where:

    • SOURCE_BUCKET_NAME is the name of the bucket containing the object to copy. For example, my-source-bucket .
    • SOURCE_OBJECT_NAME is the name of the object to copy. For example, pets/dog.png .
    • DESTINATION_BUCKET_NAME is the name of the bucket to copy the object to. For example, my-destination-bucket .
    • DESTINATION_OBJECT_NAME is the name of the destination object. For example, pets/cat.png .
    • KEY is the context key to attach to an object. For example, Department . You can specify multiple key-value pairs or keys separated by commas.
    • VALUE is the value to associate with the context key. For example, Human resources .

    JSON API

    To override contexts when copying an object, include the contexts.custom property in the request body:

    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 contexts to attach to the destination object:

        
 { 
  
 "contexts" 
 : 
  
 { 
  
 "custom" 
 : 
  
 { 
  
 " KEY 
" 
 : 
  
 { 
  
 "value" 
 : 
  
 " VALUE 
" 
  
 } 
  
 } 
  
 } 
  
 }

      Where:

      • KEY is the context key to attach to an object. For example, Department .
      • VALUE is the value to associate with the context key. For example, Human resources .

    3. Use cURL to call the JSON API with a POST 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/ SOURCE_BUCKET_NAME 
/o/ SOURCE_OBJECT_NAME 
/copyTo/b/ DESTINATION_BUCKET_NAME 
/o/ DESTINATION_OBJECT_NAME 
"

      Where:

      • JSON_FILE_NAME is the path to the JSON file that includes the object contexts information.
      • SOURCE_BUCKET_NAME is the name of the bucket that contains the object to copy. For example, my-source-bucket .
      • SOURCE_OBJECT_NAME is the URL-encoded name of the object to copy. For example, employees.txt .
      • DESTINATION_BUCKET_NAME is the name of the bucket to copy the object to. For example, my-destination-bucket .
      • DESTINATION_OBJECT_NAME is the URL-encoded name of the destination object. For example, employees-backup.txt .

    To remove all source contexts without providing an override, use the dropContextGroups=custom query parameter in your request:

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/ SOURCE_BUCKET_NAME 
/o/ SOURCE_OBJECT_NAME 
/copyTo/b/ DESTINATION_BUCKET_NAME 
/o/ DESTINATION_OBJECT_NAME 
?dropContextGroups=custom"

    To preserve contexts, omit the contexts.custom property from the request body and exclude dropContextGroups=custom in query parameters:

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/ SOURCE_BUCKET_NAME 
/o/ SOURCE_OBJECT_NAME 
/copyTo/b/ DESTINATION_BUCKET_NAME 
/o/ DESTINATION_OBJECT_NAME 
"

    For information about how contexts behave during copy operations, see the dropContextGroups query parameter.

    Rewrite objects

    By default, Cloud Storage preserves object contexts from the source object during a rewrite operation, even if you override other metadata. To modify object contexts during a rewrite operation, complete the following steps:

    Command line

    The gcloud storage cp command, gcloud storage rsync command, and gcloud storage mv commands perform rewrites automatically when necessary, for example, when copying objects between different locations or storage classes. gcloud storage cp and gcloud storage rsync result in a source and destination object, while gcloud storage mv creates the destination object and removes the source object. Because these operations create a new object, you can also modify or attach contexts as part of the same command by using any of the following flags:

    • The --custom-contexts flag to set new contexts for the destination object.

    • The --clear-custom-contexts flag to prevent contexts from the source object from being attached to the destination object.

    • A combination of the --update-custom-contexts and --remove-custom-contexts flags to modify individual contexts from the source object before attaching them to the destination object.

    To set new contexts when you copy an object, use the gcloud storage cp command:

    gcloud storage cp gs:// SOURCE_BUCKET_NAME 
/ SOURCE_OBJECT_NAME 
gs:// DESTINATION_BUCKET_NAME 
/ DESTINATION_OBJECT_NAME 
--custom-contexts= KEY 
= VALUE 
,...

    Where:

    • SOURCE_BUCKET_NAME is the name of the bucket containing the object to copy. For example, my-source-bucket .
    • SOURCE_OBJECT_NAME is the name of the object to copy. For example, employees.txt .
    • DESTINATION_BUCKET_NAME is the name of the bucket to copy the object to. For example, my-destination-bucket .
    • DESTINATION_OBJECT_NAME is the name of the destination object. For example, employees-backup.txt .
    • KEY is the context key to attach to an object. For example, Department . You can specify multiple key-value pairs separated by commas.
    • VALUE is the value to associate with the context key. For example, Human resources .

    To remove all contexts from the source object when you copy an object, use the gcloud storage cp command:

    gcloud storage cp gs:// SOURCE_BUCKET_NAME 
/ SOURCE_OBJECT_NAME 
gs:// DESTINATION_BUCKET_NAME 
/ DESTINATION_OBJECT_NAME 
--clear-custom-contexts

    Where:

    • SOURCE_BUCKET_NAME is the name of the bucket containing the object to copy. For example, my-source-bucket .
    • SOURCE_OBJECT_NAME is the name of the object to copy. For example, pets/dog.png .
    • DESTINATION_BUCKET_NAME is the name of the bucket to copy the object to. For example, my-destination-bucket .
    • DESTINATION_OBJECT_NAME is the name of the destination object. For example, pets/cat.png .

    To modify individual contexts from the source object when you copy an object, use the gcloud storage cp command with --update-custom-contexts and --remove-custom-contexts :

    gcloud storage cp gs:// SOURCE_BUCKET_NAME 
/ SOURCE_OBJECT_NAME 
gs:// DESTINATION_BUCKET_NAME 
/ DESTINATION_OBJECT_NAME 
--update-custom-contexts= KEY 
= VALUE 
,... --remove-custom-contexts= KEY 
,...

    Where:

    • SOURCE_BUCKET_NAME is the name of the bucket containing the object to copy. For example, my-source-bucket .
    • SOURCE_OBJECT_NAME is the name of the object to copy. For example, pets/dog.png .
    • DESTINATION_BUCKET_NAME is the name of the bucket to copy the object to. For example, my-destination-bucket .
    • DESTINATION_OBJECT_NAME is the name of the destination object. For example, pets/cat.png .
    • KEY is the context key to attach to an object. For example, Department . You can specify multiple key-value pairs or keys separated by commas.
    • VALUE is the value to associate with the context key. For example, Human resources .

    JSON API

    To override contexts when rewriting an object, include the contexts.custom property in the request body:

    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 contexts to attach to the destination object:

        
 { 
  
 "contexts" 
 : 
  
 { 
  
 "custom" 
 : 
  
 { 
  
 " KEY 
" 
 : 
  
 { 
  
 "value" 
 : 
  
 " VALUE 
" 
  
 } 
  
 } 
  
 } 
  
 }

      Where:

      • KEY is the context key to attach to an object. For example, Department .
      • VALUE is the value to associate with the context key. For example, Human resources .

    3. Use cURL to call the JSON API with a POST rewrite 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/ SOURCE_BUCKET_NAME 
/o/ SOURCE_OBJECT_NAME 
/rewriteTo/b/ DESTINATION_BUCKET_NAME 
/o/ DESTINATION_OBJECT_NAME 
"

      Where:

      • JSON_FILE_NAME is the path to the JSON file that includes the object contexts information.
      • SOURCE_BUCKET_NAME is the name of the bucket that contains the object to rewrite. For example, my-source-bucket .
      • SOURCE_OBJECT_NAME is the URL-encoded name of the object to rewrite. For example, employees.txt .
      • DESTINATION_BUCKET_NAME is the name of the bucket to rewrite the object to. For example, my-destination-bucket .
      • DESTINATION_OBJECT_NAME is the URL-encoded name of the destination object. For example, employees-backup.txt .

    To remove all source contexts without providing an override, use the dropContextGroups=custom query parameter in your request:

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/ SOURCE_BUCKET_NAME 
/o/ SOURCE_OBJECT_NAME 
/rewriteTo/b/ DESTINATION_BUCKET_NAME 
/o/ DESTINATION_OBJECT_NAME 
?dropContextGroups=custom"

    To preserve contexts, omit the contexts.custom property from the request body and exclude dropContextGroups=custom in query parameters:

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/ SOURCE_BUCKET_NAME 
/o/ SOURCE_OBJECT_NAME 
/rewriteTo/b/ DESTINATION_BUCKET_NAME 
/o/ DESTINATION_OBJECT_NAME 
"

    For information about how contexts behave during rewrite operations, see the dropContextGroups query parameter.

    Compose objects

    The gcloud storage objects compose command and the JSON API compose method merge contexts from the source objects and attach them to the destination objects by default. Cloud Storage resolves conflicts by prioritizing contexts from source objects processed later. For more information about the object context behavior during a compose operation, see Composite object contexts .

    Command line

    To specify new contexts for the destination object when composing objects, use the --contexts flag:

    gcloud storage objects compose gs:// BUCKET_NAME 
/ SOURCE_OBJECT_1 
gs:// BUCKET_NAME 
/ SOURCE_OBJECT_2 
gs:// BUCKET_NAME 
/ DESTINATION_OBJECT_NAME 
--contexts= KEY 
= VALUE 
,...

    Where:

    • BUCKET_NAME is the name of the bucket that contains the source objects and where the destination object is created. For example, my-bucket .
    • SOURCE_OBJECT_1 and SOURCE_OBJECT_2 are source objects to compose.
    • DESTINATION_OBJECT_NAME is the name of the destination object to be created. For example, my-composite-object .
    • KEY is the context key to attach to an object. For example, Department . You can specify multiple key-value pairs separated by commas.
    • VALUE is the value to associate with the context key. For example, Human resources .

    To prevent source contexts from being attached to composite objects, use the --clear-custom-contexts flag:

    gcloud storage objects compose gs:// BUCKET_NAME 
/ SOURCE_OBJECT_1 
gs:// BUCKET_NAME 
/ SOURCE_OBJECT_2 
gs:// BUCKET_NAME 
/ DESTINATION_OBJECT_NAME 
--clear-custom-contexts

    Where:

    • BUCKET_NAME is the name of the bucket that contains source objects and where the destination object is created. For example, my-bucket .
    • SOURCE_OBJECT_1 and SOURCE_OBJECT_2 are the source objects to compose.
    • DESTINATION_OBJECT_NAME is the name of the destination object to be created. For example, my-composite-object .

    JSON API

    To specify new contexts for the destination object when composing objects, include contexts in the destination property of the request body.

    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 request body:

       { 
  
 "sourceObjects" 
 : 
  
 [ 
  
 { 
 "name" 
 : 
  
 " SOURCE_OBJECT_1 
" 
 }, 
  
 { 
 "name" 
 : 
  
 " SOURCE_OBJECT_2 
" 
 } 
  
 ], 
  
 "destination" 
 : 
  
 { 
  
 "contentType" 
 : 
  
 "text/plain" 
 , 
  
 "contexts" 
 : 
  
 { 
  
 "custom" 
 : 
  
 { 
  
 " KEY 
" 
 : 
  
 { 
  
 "value" 
 : 
  
 " VALUE 
" 
  
 } 
  
 } 
  
 } 
  
 } 
 }

      Where:

      • SOURCE_OBJECT_1 and SOURCE_OBJECT_2 are source objects to compose.
      • KEY is the context key to attach to an object. For example, Department .
      • VALUE is the value to associate with the context key. For example, Human resources .

    3. Use cURL to call the JSON API with a POST compose 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/ DESTINATION_OBJECT_NAME 
/compose"

      Where:

      • JSON_FILE_NAME is the path to the JSON file that includes the request body.
      • BUCKET_NAME is the name of the bucket that contains source objects and where the destination object will be created. For example, my-bucket .
      • DESTINATION_OBJECT_NAME is the name of the destination object to be created. For example, my-composite-object .

    To prevent source contexts from being attached to composite objects, use the dropContextGroups=custom query parameter in your request:

    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 request body:

       { 
  
 "sourceObjects" 
 : 
  
 [ 
  
 { 
 "name" 
 : 
  
 " SOURCE_OBJECT_1 
" 
 }, 
  
 { 
 "name" 
 : 
  
 " SOURCE_OBJECT_2 
" 
 } 
  
 ], 
  
 "destination" 
 : 
  
 { 
  
 "contentType" 
 : 
  
 "text/plain" 
 } 
 }

      Where:

      • SOURCE_OBJECT_1 and SOURCE_OBJECT_2 are source objects to compose.

    3. Use cURL to call the JSON API with a POST compose 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/ DESTINATION_OBJECT_NAME 
/compose?dropContextGroups=custom"

      Where:

      • JSON_FILE_NAME is the path to the JSON file that includes the request body.
      • BUCKET_NAME is the name of the bucket that contains source objects and where the destination object will be created. For example, my-bucket .
      • DESTINATION_OBJECT_NAME is the name of the destination object to be created. For example, my-composite-object .

    What's next

    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: