Use object contexts

Command line

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

gcloud alpha 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/dog.png .
• 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 alpha storage rsync command, use the --custom-contexts flag or the --custom-contexts-file flag:

gcloud alpha 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:

• Multipart uploads

• Resumable uploads

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 .

Command line

Use the gcloud alpha storage objects update command:

gcloud alpha 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, pets/dog.png .

• 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 --clear-custom-contexts .

  • 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 an object. For example, Human resources .

If successful, the response looks like the following example:

Patching gs://my-bucket/pets/dog.png#1560574162144861...
  Completed 1

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 
 ); 
  
 } 
  
 } 
 }