Using bucket labels

This page shows you how to add, modify, remove, and view the labels set on a bucket in Cloud Storage.

Required roles

In order to get the required permissions for adding and managing bucket labels, ask your administrator to grant you the Storage Admin ( roles/storage.admin ) IAM role on the bucket.

This predefined role contains the permissions required to add and manage bucket labels. To see the exact permissions that are required, expand the Required permissionssection:

Required permissions

storage.buckets.get
storage.buckets.list
- This permission is only required if you plan on using the Google Cloud console to perform the instructions on this page.
storage.buckets.update

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

For instructions on granting roles on buckets, see Set and manage IAM policies on buckets .

Add, modify, or remove a bucket's labels

Console

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the list of buckets, click the name of the bucket for which you want to add, modify, or remove labels.
In the Bucket detailspage, click the Configurationtab.
Click the Editicon ( ) for Labels.

The label editor window appears.
1. To add a label, click the Add labelbutton, and specify a key and a value for your label.
2. To modify an existing label, click its Valueand a enter a new value.
3. To remove a label, click the Trash iconassociated with the label you want to remove.
Click Save.

To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, see Troubleshooting .

Command line

To add a new label or update an existing label, use the gcloud storage buckets update command with the --update-labels flag. For example:

gcloud storage buckets update gs:// BUCKET_NAME 
--update-labels= KEY_1 
= VALUE_1

Where

BUCKET_NAME is the name of the bucket that the label applies to. For example, my-bucket .
KEY_1 is the key name for your label. For example, pet .
VALUE_1 is the value for your label. For example, dog .

To remove an existing label, use the -remove-labels flag. For example:

gcloud storage buckets update gs:// BUCKET_NAME 
--remove-labels= KEY_1

You can change multiple labels using the previous commands by including the labels in a comma-separated list within the relevant flag. For example, --update-labels=blue-key=cyan,red-key=ruby .

To remove all labels attached to a bucket, use the following command:

gcloud storage buckets update gs:// BUCKET_NAME 
--clear-labels

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

The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket:

  namespace 
  
 gcs 
  
 = 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 storage 
 ; 
 using 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 StatusOr 
 ; 
 []( 
 gcs 
 :: 
 Client 
  
 client 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 bucket_name 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 label_key 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 label_value 
 ) 
  
 { 
  
 StatusOr<gcs 
 :: 
 BucketMetadata 
>  
 updated 
  
 = 
  
 client 
 . 
 PatchBucket 
 ( 
  
 bucket_name 
 , 
  
 gcs 
 :: 
 BucketMetadataPatchBuilder 
 (). 
 SetLabel 
 ( 
 label_key 
 , 
  
 label_value 
 )); 
  
 if 
  
 ( 
 ! 
 updated 
 ) 
  
 throw 
  
 std 
 :: 
 move 
 ( 
 updated 
 ). 
 status 
 (); 
  
 std 
 :: 
 cout 
 << 
 "Successfully set label " 
 << 
 label_key 
 << 
 " to " 
 << 
 label_value 
 << 
 " on bucket  " 
 << 
 updated 
 - 
> name 
 () 
 << 
 "." 
 ; 
  
 std 
 :: 
 cout 
 << 
 " The bucket labels are now:" 
 ; 
  
 for 
  
 ( 
 auto 
  
 const 
&  
 kv 
  
 : 
  
 updated 
 - 
> labels 
 ()) 
  
 { 
  
 std 
 :: 
 cout 
 << 
 " 
 \n 
 " 
 << 
 kv 
 . 
 first 
 << 
 ": " 
 << 
 kv 
 . 
 second 
 ; 
  
 } 
  
 std 
 :: 
 cout 
 << 
 " 
 \n 
 " 
 ; 
 }

The following sample removes the specified label from a bucket:

  namespace 
  
 gcs 
  
 = 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 storage 
 ; 
 using 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 StatusOr 
 ; 
 []( 
 gcs 
 :: 
 Client 
  
 client 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 bucket_name 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 label_key 
 ) 
  
 { 
  
 StatusOr<gcs 
 :: 
 BucketMetadata 
>  
 updated 
  
 = 
  
 client 
 . 
 PatchBucket 
 ( 
  
 bucket_name 
 , 
  
 gcs 
 :: 
 BucketMetadataPatchBuilder 
 (). 
 ResetLabel 
 ( 
 label_key 
 )); 
  
 if 
  
 ( 
 ! 
 updated 
 ) 
  
 throw 
  
 std 
 :: 
 move 
 ( 
 updated 
 ). 
 status 
 (); 
  
 std 
 :: 
 cout 
 << 
 "Successfully reset label " 
 << 
 label_key 
 << 
 " on bucket  " 
 << 
 updated 
 - 
> name 
 () 
 << 
 "." 
 ; 
  
 if 
  
 ( 
 updated 
 - 
> labels 
 (). 
 empty 
 ()) 
  
 { 
  
 std 
 :: 
 cout 
 << 
 " The bucket now has no labels. 
 \n 
 " 
 ; 
  
 return 
 ; 
  
 } 
  
 std 
 :: 
 cout 
 << 
 " The bucket labels are now:" 
 ; 
  
 for 
  
 ( 
 auto 
  
 const 
&  
 kv 
  
 : 
  
 updated 
 - 
> labels 
 ()) 
  
 { 
  
 std 
 :: 
 cout 
 << 
 " 
 \n 
 " 
 << 
 kv 
 . 
 first 
 << 
 ": " 
 << 
 kv 
 . 
 second 
 ; 
  
 } 
  
 std 
 :: 
 cout 
 << 
 " 
 \n 
 " 
 ; 
 }

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

The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket:

  using 
  
 Google.Apis.Storage.v1.Data 
 ; 
 using 
  
  Google.Cloud.Storage.V1 
 
 ; 
 using 
  
 System 
 ; 
 using 
  
 System.Collections.Generic 
 ; 
 public 
  
 class 
  
 BucketAddLabelSample 
 { 
  
 public 
  
 Bucket 
  
 BucketAddLabel 
 ( 
  
 string 
  
 bucketName 
  
 = 
  
 "your-bucket-name" 
 , 
  
 string 
  
 labelKey 
  
 = 
  
 "label-key-to-add" 
 , 
  
 string 
  
 labelValue 
  
 = 
  
 "label-value-to-add" 
 ) 
  
 { 
  
 var 
  
 storage 
  
 = 
  
  StorageClient 
 
 . 
  Create 
 
 (); 
  
 var 
  
 bucket 
  
 = 
  
 storage 
 . 
 GetBucket 
 ( 
 bucketName 
 ); 
  
 if 
  
 ( 
 bucket 
 . 
 Labels 
  
 == 
  
 null 
 ) 
  
 { 
  
 bucket 
 . 
 Labels 
  
 = 
  
 new 
  
 Dictionary<string 
 , 
  
 string 
> (); 
  
 } 
  
 bucket 
 . 
 Labels 
 . 
 Add 
 ( 
 labelKey 
 , 
  
 labelValue 
 ); 
  
 bucket 
  
 = 
  
 storage 
 . 
 UpdateBucket 
 ( 
 bucket 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Added label {labelKey} with value {labelValue} to bucket {bucketName}." 
 ); 
  
 return 
  
 bucket 
 ; 
  
 } 
 }

The following sample removes the specified label from a bucket:

  using 
  
 Google.Apis.Storage.v1.Data 
 ; 
 using 
  
  Google.Cloud.Storage.V1 
 
 ; 
 using 
  
 System 
 ; 
 public 
  
 class 
  
 BucketRemoveLabelSample 
 { 
  
 public 
  
 Bucket 
  
 BucketRemoveLabel 
 ( 
 string 
  
 bucketName 
  
 = 
  
 "your-bucket-name" 
 , 
  
 string 
  
 labelKey 
  
 = 
  
 "label-key-to-remove" 
 ) 
  
 { 
  
 var 
  
 storage 
  
 = 
  
  StorageClient 
 
 . 
  Create 
 
 (); 
  
 var 
  
 bucket 
  
 = 
  
 storage 
 . 
 GetBucket 
 ( 
 bucketName 
 ); 
  
 if 
  
 ( 
 bucket 
 . 
 Labels 
  
 != 
  
 null 
 && 
 bucket 
 . 
 Labels 
 . 
 Keys 
 . 
 Contains 
 ( 
 labelKey 
 )) 
  
 { 
  
 bucket 
 . 
 Labels 
 . 
 Remove 
 ( 
 labelKey 
 ); 
  
 bucket 
  
 = 
  
 storage 
 . 
 UpdateBucket 
 ( 
 bucket 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Removed label {labelKey} from bucket {bucketName}." 
 ); 
  
 } 
  
 else 
  
 { 
  
 Console 
 . 
 WriteLine 
 ( 
 $"No such label available on {bucketName}." 
 ); 
  
 } 
  
 return 
  
 bucket 
 ; 
  
 } 
 }

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

The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket:

  import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 "time" 
  
 "cloud.google.com/go/storage" 
 ) 
 // addBucketLabel adds a label on a bucket. 
 func 
  
 addBucketLabel 
 ( 
 w 
  
 io 
 . 
  Writer 
 
 , 
  
 bucketName 
 , 
  
 labelName 
 , 
  
 labelValue 
  
 string 
 ) 
  
 error 
  
 { 
  
 // bucketName := "bucket-name" 
  
 // labelName := "label-name" 
  
 // labelValue := "label-value" 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 client 
 , 
  
 err 
  
 := 
  
 storage 
 . 
 NewClient 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "storage.NewClient: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 client 
 . 
 Close 
 () 
  
 ctx 
 , 
  
 cancel 
  
 := 
  
 context 
 . 
 WithTimeout 
 ( 
 ctx 
 , 
  
 time 
 . 
 Second 
 * 
 10 
 ) 
  
 defer 
  
 cancel 
 () 
  
 bucket 
  
 := 
  
 client 
 . 
  Bucket 
 
 ( 
 bucketName 
 ) 
  
 bucketAttrsToUpdate 
  
 := 
  
 storage 
 . 
  BucketAttrsToUpdate 
 
 {} 
  
 bucketAttrsToUpdate 
 . 
  SetLabel 
 
 ( 
 labelName 
 , 
  
 labelValue 
 ) 
  
 if 
  
 _ 
 , 
  
 err 
  
 := 
  
 bucket 
 . 
 Update 
 ( 
 ctx 
 , 
  
 bucketAttrsToUpdate 
 ); 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "Bucket(%q).Update: %w" 
 , 
  
 bucketName 
 , 
  
 err 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Added label %q with value %q to bucket %v\n" 
 , 
  
 labelName 
 , 
  
 labelValue 
 , 
  
 bucketName 
 ) 
  
 return 
  
 nil 
 }

The following sample removes the specified label from a bucket:

  import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 "time" 
  
 "cloud.google.com/go/storage" 
 ) 
 // removeBucketLabel removes a label on a bucket. 
 func 
  
 removeBucketLabel 
 ( 
 w 
  
 io 
 . 
  Writer 
 
 , 
  
 bucketName 
 , 
  
 labelName 
  
 string 
 ) 
  
 error 
  
 { 
  
 // bucketName := "bucket-name" 
  
 // labelName := "label-name" 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 client 
 , 
  
 err 
  
 := 
  
 storage 
 . 
 NewClient 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "storage.NewClient: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 client 
 . 
 Close 
 () 
  
 ctx 
 , 
  
 cancel 
  
 := 
  
 context 
 . 
 WithTimeout 
 ( 
 ctx 
 , 
  
 time 
 . 
 Second 
 * 
 10 
 ) 
  
 defer 
  
 cancel 
 () 
  
 bucket 
  
 := 
  
 client 
 . 
  Bucket 
 
 ( 
 bucketName 
 ) 
  
 bucketAttrsToUpdate 
  
 := 
  
 storage 
 . 
  BucketAttrsToUpdate 
 
 {} 
  
 bucketAttrsToUpdate 
 . 
  DeleteLabel 
 
 ( 
 labelName 
 ) 
  
 if 
  
 _ 
 , 
  
 err 
  
 := 
  
 bucket 
 . 
 Update 
 ( 
 ctx 
 , 
  
 bucketAttrsToUpdate 
 ); 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "Bucket(%q).Update: %w" 
 , 
  
 bucketName 
 , 
  
 err 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Removed label %q from bucket %v\n" 
 , 
  
 labelName 
 , 
  
 bucketName 
 ) 
  
 return 
  
 nil 
 }

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 .

The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket:

  import 
  
 com.google.cloud.storage. Bucket 
 
 ; 
 import 
  
 com.google.cloud.storage. Storage 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageOptions 
 
 ; 
 import 
  
 java.util.HashMap 
 ; 
 import 
  
 java.util.Map 
 ; 
 public 
  
 class 
 AddBucketLabel 
  
 { 
  
 public 
  
 static 
  
 void 
  
 addBucketLabel 
 ( 
  
 String 
  
 projectId 
 , 
  
 String 
  
 bucketName 
 , 
  
 String 
  
 labelKey 
 , 
  
 String 
  
 labelValue 
 ) 
  
 { 
  
 // The ID of your GCP project 
  
 // String projectId = "your-project-id"; 
  
 // The ID of your GCS bucket 
  
 // String bucketName = "your-unique-bucket-name"; 
  
 // The key of the label to add 
  
 // String labelKey = "label-key-to-add"; 
  
 // The value of the label to add 
  
 // String labelValue = "label-value-to-add"; 
  
 Map<String 
 , 
  
 String 
>  
 newLabels 
  
 = 
  
 new 
  
 HashMap 
<> (); 
  
 newLabels 
 . 
 put 
 ( 
 labelKey 
 , 
  
 labelValue 
 ); 
  
  Storage 
 
  
 storage 
  
 = 
  
  StorageOptions 
 
 . 
 newBuilder 
 (). 
 setProjectId 
 ( 
 projectId 
 ). 
 build 
 (). 
  getService 
 
 (); 
  
  Bucket 
 
  
 bucket 
  
 = 
  
 storage 
 . 
  get 
 
 ( 
 bucketName 
 ); 
  
 Map<String 
 , 
  
 String 
>  
 labels 
  
 = 
  
 bucket 
 . 
 getLabels 
 (); 
  
 if 
  
 ( 
 labels 
  
 != 
  
 null 
 ) 
  
 { 
  
 newLabels 
 . 
 putAll 
 ( 
 labels 
 ); 
  
 } 
  
 bucket 
 . 
  toBuilder 
 
 (). 
 setLabels 
 ( 
 newLabels 
 ). 
 build 
 (). 
 update 
 (); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
  
 "Added label " 
  
 + 
  
 labelKey 
  
 + 
  
 " with value " 
  
 + 
  
 labelValue 
  
 + 
  
 " to bucket " 
  
 + 
  
 bucketName 
  
 + 
  
 "." 
 ); 
  
 } 
 }

The following sample removes the specified label from a bucket:

  import 
  
 com.google.cloud.storage. Bucket 
 
 ; 
 import 
  
 com.google.cloud.storage. Storage 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageOptions 
 
 ; 
 import 
  
 java.util.HashMap 
 ; 
 import 
  
 java.util.Map 
 ; 
 public 
  
 class 
 RemoveBucketLabel 
  
 { 
  
 public 
  
 static 
  
 void 
  
 removeBucketLabel 
 ( 
 String 
  
 projectId 
 , 
  
 String 
  
 bucketName 
 , 
  
 String 
  
 labelKey 
 ) 
  
 { 
  
 // The ID of your GCP project 
  
 // String projectId = "your-project-id"; 
  
 // The ID of your GCS bucket 
  
 // String bucketName = "your-unique-bucket-name"; 
  
 // The key of the label to remove from the bucket 
  
 // String labelKey = "label-key-to-remove"; 
  
  Storage 
 
  
 storage 
  
 = 
  
  StorageOptions 
 
 . 
 newBuilder 
 (). 
 setProjectId 
 ( 
 projectId 
 ). 
 build 
 (). 
  getService 
 
 (); 
  
 Map<String 
 , 
  
 String 
>  
 labelsToRemove 
  
 = 
  
 new 
  
 HashMap 
<> (); 
  
 labelsToRemove 
 . 
 put 
 ( 
 labelKey 
 , 
  
 null 
 ); 
  
  Bucket 
 
  
 bucket 
  
 = 
  
 storage 
 . 
  get 
 
 ( 
 bucketName 
 ); 
  
 Map<String 
 , 
  
 String 
>  
 labels 
 ; 
  
 if 
  
 ( 
 bucket 
 . 
 getLabels 
 () 
  
 == 
  
 null 
 ) 
  
 { 
  
 labels 
  
 = 
  
 new 
  
 HashMap 
<> (); 
  
 } 
  
 else 
  
 { 
  
 labels 
  
 = 
  
 new 
  
 HashMap 
 ( 
 bucket 
 . 
 getLabels 
 ()); 
  
 } 
  
 labels 
 . 
 putAll 
 ( 
 labelsToRemove 
 ); 
  
 bucket 
 . 
  toBuilder 
 
 (). 
 setLabels 
 ( 
 labels 
 ). 
 build 
 (). 
 update 
 (); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Removed label " 
  
 + 
  
 labelKey 
  
 + 
  
 " from bucket " 
  
 + 
  
 bucketName 
 ); 
  
 } 
 }

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

The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket:

  /** 
 * TODO(developer): Uncomment the following lines before running the sample. 
 */ 
 // The ID of your GCS bucket 
 // const bucketName = 'your-unique-bucket-name'; 
 // The key of the label to add 
 // const labelKey = 'label-key-to-add'; 
 // The value of the label to add 
 // const labelValue = 'label-value-to-add'; 
 // Imports the Google Cloud client library 
 const 
  
 { 
 Storage 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/storage 
' 
 ); 
 // Creates a client 
 const 
  
 storage 
  
 = 
  
 new 
  
 Storage 
 (); 
 const 
  
 labels 
  
 = 
  
 { 
  
 [ 
 labelKey 
 ] 
 : 
  
 labelValue 
 , 
 }; 
 async 
  
 function 
  
 addBucketLabel 
 () 
  
 { 
  
 await 
  
 storage 
 . 
 bucket 
 ( 
 bucketName 
 ). 
 setMetadata 
 ({ 
 labels 
 }); 
  
 console 
 . 
 log 
 ( 
 `Added label to bucket 
 ${ 
 bucketName 
 } 
 ` 
 ); 
 } 
 addBucketLabel 
 (). 
 catch 
 ( 
 console 
 . 
 error 
 );

The following sample removes the specified label from a bucket:

  /** 
 * TODO(developer): Uncomment the following lines before running the sample. 
 */ 
 // The ID of your GCS bucket 
 // const bucketName = 'your-unique-bucket-name'; 
 // The key of the label to remove from the bucket 
 // const labelKey = 'label-key-to-remove'; 
 // Imports the Google Cloud client library 
 const 
  
 { 
 Storage 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/storage 
' 
 ); 
 // Creates a client 
 const 
  
 storage 
  
 = 
  
 new 
  
 Storage 
 (); 
 async 
  
 function 
  
 removeBucketLabel 
 () 
  
 { 
  
 const 
  
 labels 
  
 = 
  
 {}; 
  
 // To remove a label set the value of the key to null. 
  
 labels 
 [ 
 labelKey 
 ] 
  
 = 
  
 null 
 ; 
  
 await 
  
 storage 
 . 
 bucket 
 ( 
 bucketName 
 ). 
 setMetadata 
 ({ 
 labels 
 }); 
  
 console 
 . 
 log 
 ( 
 `Removed labels from bucket 
 ${ 
 bucketName 
 } 
 ` 
 ); 
 } 
 removeBucketLabel 
 (). 
 catch 
 ( 
 console 
 . 
 error 
 );

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

The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket:

  use Google\Cloud\Storage\StorageClient; 
 /** 
 * Adds or updates a bucket label. 
 * 
 * @param string $bucketName The name of your Cloud Storage bucket. 
 *        (e.g. 'my-bucket') 
 * @param string $labelName The name of the label to add. 
 *        (e.g. 'label-key-to-add') 
 * @param string $labelValue The value of the label to add. 
 *        (e.g. 'label-value-to-add') 
 */ 
 function add_bucket_label(string $bucketName, string $labelName, string $labelValue): void 
 { 
 $storage = new StorageClient(); 
 $bucket = $storage->bucket($bucketName); 
 $newLabels = [$labelName => $labelValue]; 
 $bucket->update(['labels' => $newLabels]); 
 printf('Added label %s (%s) to %s' . PHP_EOL, $labelName, $labelValue, $bucketName); 
 }

The following sample removes the specified label from a bucket:

  use Google\Cloud\Storage\StorageClient; 
 /** 
 * Removes a label from a bucket. 
 * 
 * @param string $bucketName The name of your Cloud Storage bucket. 
 *        (e.g. 'my-bucket') 
 * @param string $labelName The name of the label to remove. 
 *        (e.g. 'label-key-to-remove') 
 */ 
 function remove_bucket_label(string $bucketName, string $labelName): void 
 { 
 $storage = new StorageClient(); 
 $bucket = $storage->bucket($bucketName); 
 $labels = [$labelName => null]; 
 $bucket->update(['labels' => $labels]); 
 printf('Removed label %s from %s' . PHP_EOL, $labelName, $bucketName); 
 }

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

The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket:

  import 
  
 pprint 
 from 
  
 google.cloud 
  
 import 
  storage 
 
 def 
  
 add_bucket_label 
 ( 
 bucket_name 
 ): 
  
 """Add a label to a bucket.""" 
 # bucket_name = "your-bucket-name" 
 storage_client 
 = 
  storage 
 
 . 
  Client 
 
 () 
 bucket 
 = 
 storage_client 
 . 
  get_bucket 
 
 ( 
 bucket_name 
 ) 
 labels 
 = 
 bucket 
 . 
  labels 
 
 labels 
 [ 
 "example" 
 ] 
 = 
 "label" 
 bucket 
 . 
  labels 
 
 = 
 labels 
 bucket 
 . 
 patch 
 () 
 print 
 ( 
 f 
 "Updated labels on 
 { 
 bucket 
 . 
 name 
 } 
 ." 
 ) 
 pprint 
 . 
 pprint 
 ( 
 bucket 
 . 
  labels 
 
 )

The following sample removes the specified label from a bucket:

  import 
  
 pprint 
 from 
  
 google.cloud 
  
 import 
  storage 
 
 def 
  
 remove_bucket_label 
 ( 
 bucket_name 
 ): 
  
 """Remove a label from a bucket.""" 
 # bucket_name = "your-bucket-name" 
 storage_client 
 = 
  storage 
 
 . 
  Client 
 
 () 
 bucket 
 = 
 storage_client 
 . 
  get_bucket 
 
 ( 
 bucket_name 
 ) 
 labels 
 = 
 bucket 
 . 
  labels 
 
 if 
 "example" 
 in 
 labels 
 : 
 del 
 labels 
 [ 
 "example" 
 ] 
 bucket 
 . 
  labels 
 
 = 
 labels 
 bucket 
 . 
 patch 
 () 
 print 
 ( 
 f 
 "Removed labels on 
 { 
 bucket 
 . 
 name 
 } 
 ." 
 ) 
 pprint 
 . 
 pprint 
 ( 
 bucket 
 . 
  labels 
 
 )

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

The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket:

  def 
  
 add_bucket_label 
  
 bucket_name 
 :, 
  
 label_key 
 :, 
  
 label_value 
 : 
  
 # The ID of your GCS bucket 
  
 # bucket_name = "your-unique-bucket-name" 
  
 # The key of the label to add 
  
 # label_key = "label-key-to-add" 
  
 # The value of the label to add 
  
 # label_value = "label-value-to-add" 
  
 require 
  
 "google/cloud/storage" 
  
 storage 
  
 = 
  
 Google 
 :: 
 Cloud 
 :: 
  Storage 
 
 . 
  new 
 
  
 bucket 
  
 = 
  
 storage 
 . 
 bucket 
  
 bucket_name 
  
 bucket 
 . 
 update 
  
 do 
  
 | 
 bucket 
 | 
  
 bucket 
 . 
 labels 
 [ 
 label_key 
 ] 
  
 = 
  
 label_value 
  
 end 
  
 puts 
  
 "Added label 
 #{ 
 label_key 
 } 
 with value 
 #{ 
 label_value 
 } 
 to 
 #{ 
 bucket_name 
 } 
 " 
 end

The following sample removes the specified label from a bucket:

  def 
  
 remove_bucket_label 
  
 bucket_name 
 :, 
  
 label_key 
 : 
  
 # The ID of your GCS bucket 
  
 # bucket_name = "your-unique-bucket-name" 
  
 # The key of the label to remove from the bucket 
  
 # label_key = "label-key-to-remove" 
  
 require 
  
 "google/cloud/storage" 
  
 storage 
  
 = 
  
 Google 
 :: 
 Cloud 
 :: 
  Storage 
 
 . 
  new 
 
  
 bucket 
  
 = 
  
 storage 
 . 
 bucket 
  
 bucket_name 
  
 bucket 
 . 
 update 
  
 do 
  
 | 
 bucket 
 | 
  
 bucket 
 . 
 labels 
 [ 
 label_key 
 ] 
  
 = 
  
 nil 
  
 end 
  
 puts 
  
 "Deleted label 
 #{ 
 label_key 
 } 
 from 
 #{ 
 bucket_name 
 } 
 " 
 end

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 ?fields=labels"

View bucket labels

Console

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
Click the name of the bucket whose labels you want to view.
Click the Configurationtab.

The labels set on the bucket are listed in the Labelsfield.

To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, see Troubleshooting .

Command line

Use the gcloud storage buckets describe command with the --format flag:

gcloud storage buckets describe gs:// BUCKET_NAME 
--format="default(labels)"

Where BUCKET_NAME is the name of the bucket whose labels you want to view. For example, my-bucket .

If successful and labels exist for the bucket, the response is similar to the following:

labels:
  red-key: ruby
  blue-key: cyan

If successful and labels to not exist for the bucket, the response is similar to the following:

null

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

To view a bucket's labels, follow the instructions for displaying a bucket's metadata and look for the label field in the response.

  namespace 
  
 gcs 
  
 = 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 storage 
 ; 
 using 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 StatusOr 
 ; 
 []( 
 gcs 
 :: 
 Client 
  
 client 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 bucket_name 
 ) 
  
 { 
  
 StatusOr<gcs 
 :: 
 BucketMetadata 
>  
 bucket_metadata 
  
 = 
  
 client 
 . 
 GetBucketMetadata 
 ( 
 bucket_name 
 ); 
  
 if 
  
 ( 
 ! 
 bucket_metadata 
 ) 
  
 throw 
  
 std 
 :: 
 move 
 ( 
 bucket_metadata 
 ). 
 status 
 (); 
  
 std 
 :: 
 cout 
 << 
 "The metadata for bucket " 
 << 
 bucket_metadata 
 - 
> name 
 () 
 << 
 " is " 
 << 
 * 
 bucket_metadata 
 << 
 " 
 \n 
 " 
 ; 
 }

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

To view a bucket's labels, follow the instructions for displaying a bucket's metadata and look for the label field in the response.

  using 
  
 Google.Apis.Storage.v1.Data 
 ; 
 using 
  
  Google.Cloud.Storage.V1 
 
 ; 
 using 
  
 System 
 ; 
 public 
  
 class 
  
 GetBucketMetadataSample 
 { 
  
 public 
  
 Bucket 
  
 GetBucketMetadata 
 ( 
 string 
  
 bucketName 
  
 = 
  
 "your-unique-bucket-name" 
 ) 
  
 { 
  
 var 
  
 storage 
  
 = 
  
  StorageClient 
 
 . 
  Create 
 
 (); 
  
 var 
  
 bucket 
  
 = 
  
 storage 
 . 
 GetBucket 
 ( 
 bucketName 
 , 
  
 new 
  
  GetBucketOptions 
 
  
 { 
  
 Projection 
  
 = 
  
  Projection 
 
 . 
  Full 
 
  
 }); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Bucket:\t{bucket.Name}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Acl:\t{bucket. Acl 
}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Billing:\t{bucket.Billing}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Cors:\t{bucket.Cors}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"DefaultEventBasedHold:\t{bucket.DefaultEventBasedHold}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"DefaultObjectAcl:\t{bucket.DefaultObjectAcl}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Encryption:\t{bucket.Encryption}" 
 ); 
  
 if 
  
 ( 
 bucket 
 . 
 Encryption 
  
 != 
  
 null 
 ) 
  
 { 
  
 Console 
 . 
 WriteLine 
 ( 
 $"KmsKeyName:\t{bucket.Encryption.DefaultKmsKeyName}" 
 ); 
  
 } 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Id:\t{bucket.Id}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Kind:\t{bucket.Kind}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Lifecycle:\t{bucket.Lifecycle}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Location:\t{bucket.Location}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"LocationType:\t{bucket.LocationType}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Logging:\t{bucket.Logging}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Metageneration:\t{bucket.Metageneration}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"ObjectRetention:\t{bucket.ObjectRetention}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Owner:\t{bucket.Owner}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"ProjectNumber:\t{bucket.ProjectNumber}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"RetentionPolicy:\t{bucket.RetentionPolicy}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"SelfLink:\t{bucket.SelfLink}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"StorageClass:\t{bucket.StorageClass}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"TimeCreated:\t{bucket.TimeCreated}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Updated:\t{bucket.Updated}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Versioning:\t{bucket.Versioning}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Website:\t{bucket.Website}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"TurboReplication:\t{bucket.Rpo}" 
 ); 
  
 if 
  
 ( 
 bucket 
 . 
 Labels 
  
 != 
  
 null 
 ) 
  
 { 
  
 Console 
 . 
 WriteLine 
 ( 
 "Labels:" 
 ); 
  
 foreach 
  
 ( 
 var 
  
 label 
  
 in 
  
 bucket 
 . 
 Labels 
 ) 
  
 { 
  
 Console 
 . 
 WriteLine 
 ( 
 $"{label. Key 
}:\t{label.Value}" 
 ); 
  
 } 
  
 } 
  
 return 
  
 bucket 
 ; 
  
 } 
 }

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

To view a bucket's labels, follow the instructions for displaying a bucket's metadata and look for the label field in the response.

  import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 "time" 
  
 "cloud.google.com/go/storage" 
 ) 
 // getBucketMetadata gets the bucket metadata. 
 func 
  
 getBucketMetadata 
 ( 
 w 
  
 io 
 . 
  Writer 
 
 , 
  
 bucketName 
  
 string 
 ) 
  
 ( 
 * 
 storage 
 . 
  BucketAttrs 
 
 , 
  
 error 
 ) 
  
 { 
  
 // bucketName := "bucket-name" 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 client 
 , 
  
 err 
  
 := 
  
 storage 
 . 
 NewClient 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 nil 
 , 
  
 fmt 
 . 
 Errorf 
 ( 
 "storage.NewClient: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 client 
 . 
 Close 
 () 
  
 ctx 
 , 
  
 cancel 
  
 := 
  
 context 
 . 
 WithTimeout 
 ( 
 ctx 
 , 
  
 time 
 . 
 Second 
 * 
 10 
 ) 
  
 defer 
  
 cancel 
 () 
  
 attrs 
 , 
  
 err 
  
 := 
  
 client 
 . 
  Bucket 
 
 ( 
 bucketName 
 ). 
 Attrs 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 nil 
 , 
  
 fmt 
 . 
 Errorf 
 ( 
 "Bucket(%q).Attrs: %w" 
 , 
  
 bucketName 
 , 
  
 err 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "BucketName: %v\n" 
 , 
  
 attrs 
 . 
 Name 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Location: %v\n" 
 , 
  
 attrs 
 . 
 Location 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "LocationType: %v\n" 
 , 
  
 attrs 
 . 
 LocationType 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "StorageClass: %v\n" 
 , 
  
 attrs 
 . 
 StorageClass 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Turbo replication (RPO): %v\n" 
 , 
  
 attrs 
 . 
  RPO 
 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "TimeCreated: %v\n" 
 , 
  
 attrs 
 . 
 Created 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Metageneration: %v\n" 
 , 
  
 attrs 
 . 
 MetaGeneration 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "PredefinedACL: %v\n" 
 , 
  
 attrs 
 . 
 PredefinedACL 
 ) 
  
 if 
  
 attrs 
 . 
 Encryption 
  
 != 
  
 nil 
  
 { 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "DefaultKmsKeyName: %v\n" 
 , 
  
 attrs 
 . 
 Encryption 
 . 
 DefaultKMSKeyName 
 ) 
  
 } 
  
 if 
  
 attrs 
 . 
 Website 
  
 != 
  
 nil 
  
 { 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "IndexPage: %v\n" 
 , 
  
 attrs 
 . 
 Website 
 . 
 MainPageSuffix 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "NotFoundPage: %v\n" 
 , 
  
 attrs 
 . 
 Website 
 . 
 NotFoundPage 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "DefaultEventBasedHold: %v\n" 
 , 
  
 attrs 
 . 
 DefaultEventBasedHold 
 ) 
  
 if 
  
 attrs 
 . 
  RetentionPolicy 
 
  
 != 
  
 nil 
  
 { 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "RetentionEffectiveTime: %v\n" 
 , 
  
 attrs 
 . 
  RetentionPolicy 
 
 . 
 EffectiveTime 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "RetentionPeriod: %v\n" 
 , 
  
 attrs 
 . 
  RetentionPolicy 
 
 . 
 RetentionPeriod 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "RetentionPolicyIsLocked: %v\n" 
 , 
  
 attrs 
 . 
  RetentionPolicy 
 
 . 
 IsLocked 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "ObjectRetentionMode: %v\n" 
 , 
  
 attrs 
 . 
 ObjectRetentionMode 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "RequesterPays: %v\n" 
 , 
  
 attrs 
 . 
 RequesterPays 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "VersioningEnabled: %v\n" 
 , 
  
 attrs 
 . 
 VersioningEnabled 
 ) 
  
 if 
  
 attrs 
 . 
 Logging 
  
 != 
  
 nil 
  
 { 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "LogBucket: %v\n" 
 , 
  
 attrs 
 . 
 Logging 
 . 
 LogBucket 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "LogObjectPrefix: %v\n" 
 , 
  
 attrs 
 . 
 Logging 
 . 
 LogObjectPrefix 
 ) 
  
 } 
  
 if 
  
 attrs 
 . 
  CORS 
 
  
 != 
  
 nil 
  
 { 
  
 fmt 
 . 
 Fprintln 
 ( 
 w 
 , 
  
 "CORS:" 
 ) 
  
 for 
  
 _ 
 , 
  
 v 
  
 := 
  
 range 
  
 attrs 
 . 
  CORS 
 
  
 { 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "\tMaxAge: %v\n" 
 , 
  
 v 
 . 
 MaxAge 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "\tMethods: %v\n" 
 , 
  
 v 
 . 
 Methods 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "\tOrigins: %v\n" 
 , 
  
 v 
 . 
 Origins 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "\tResponseHeaders: %v\n" 
 , 
  
 v 
 . 
 ResponseHeaders 
 ) 
  
 } 
  
 } 
  
 if 
  
 attrs 
 . 
 Labels 
  
 != 
  
 nil 
  
 { 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "\n\n\nLabels:" 
 ) 
  
 for 
  
 key 
 , 
  
 value 
  
 := 
  
 range 
  
 attrs 
 . 
 Labels 
  
 { 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "\t%v = %v\n" 
 , 
  
 key 
 , 
  
 value 
 ) 
  
 } 
  
 } 
  
 return 
  
 attrs 
 , 
  
 nil 
 }

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 .

To view a bucket's labels, follow the instructions for displaying a bucket's metadata and look for the label field in the response.

  import 
  
 com.google.cloud.storage. Bucket 
 
 ; 
 import 
  
 com.google.cloud.storage. BucketInfo 
 
 ; 
 import 
  
 com.google.cloud.storage. Storage 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageOptions 
 
 ; 
 import 
  
 java.util.Map 
 ; 
 public 
  
 class 
 GetBucketMetadata 
  
 { 
  
 public 
  
 static 
  
 void 
  
 getBucketMetadata 
 ( 
 String 
  
 projectId 
 , 
  
 String 
  
 bucketName 
 ) 
  
 { 
  
 // The ID of your GCP project 
  
 // String projectId = "your-project-id"; 
  
 // The ID of your GCS bucket 
  
 // String bucketName = "your-unique-bucket-name"; 
  
  Storage 
 
  
 storage 
  
 = 
  
  StorageOptions 
 
 . 
 newBuilder 
 (). 
 setProjectId 
 ( 
 projectId 
 ). 
 build 
 (). 
  getService 
 
 (); 
  
 // Select all fields. Fields can be selected individually e.g. Storage.BucketField.NAME 
  
  Bucket 
 
  
 bucket 
  
 = 
  
 storage 
 . 
  get 
 
 ( 
 bucketName 
 , 
  
 Storage 
 . 
 BucketGetOption 
 . 
 fields 
 ( 
 Storage 
 . 
 BucketField 
 . 
 values 
 ())); 
  
 // Print bucket metadata 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "BucketName: " 
  
 + 
  
 bucket 
 . 
 getName 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "DefaultEventBasedHold: " 
  
 + 
  
 bucket 
 . 
  getDefaultEventBasedHold 
 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "DefaultKmsKeyName: " 
  
 + 
  
 bucket 
 . 
  getDefaultKmsKeyName 
 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Id: " 
  
 + 
  
 bucket 
 . 
 getGeneratedId 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "IndexPage: " 
  
 + 
  
 bucket 
 . 
  getIndexPage 
 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Location: " 
  
 + 
  
 bucket 
 . 
 getLocation 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "LocationType: " 
  
 + 
  
 bucket 
 . 
  getLocationType 
 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Metageneration: " 
  
 + 
  
 bucket 
 . 
 getMetageneration 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "NotFoundPage: " 
  
 + 
  
 bucket 
 . 
  getNotFoundPage 
 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "RetentionEffectiveTime: " 
  
 + 
  
 bucket 
 . 
  getRetentionEffectiveTime 
 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "RetentionPeriod: " 
  
 + 
  
 bucket 
 . 
  getRetentionPeriod 
 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "RetentionPolicyIsLocked: " 
  
 + 
  
 bucket 
 . 
  retentionPolicyIsLocked 
 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "RequesterPays: " 
  
 + 
  
 bucket 
 . 
 requesterPays 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "SelfLink: " 
  
 + 
  
 bucket 
 . 
 getSelfLink 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "StorageClass: " 
  
 + 
  
 bucket 
 . 
 getStorageClass 
 (). 
  name 
 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "TimeCreated: " 
  
 + 
  
 bucket 
 . 
 getCreateTime 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "VersioningEnabled: " 
  
 + 
  
 bucket 
 . 
  versioningEnabled 
 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "ObjectRetention: " 
  
 + 
  
 bucket 
 . 
  getObjectRetention 
 
 ()); 
  
 if 
  
 ( 
 bucket 
 . 
 getLabels 
 () 
  
 != 
  
 null 
 ) 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "\n\n\nLabels:" 
 ); 
  
 for 
  
 ( 
 Map 
 . 
 Entry<String 
 , 
  
 String 
>  
 label 
  
 : 
  
 bucket 
 . 
 getLabels 
 (). 
 entrySet 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 label 
 . 
 getKey 
 () 
  
 + 
  
 "=" 
  
 + 
  
 label 
 . 
 getValue 
 ()); 
  
 } 
  
 } 
  
 if 
  
 ( 
 bucket 
 . 
 getLifecycleRules 
 () 
  
 != 
  
 null 
 ) 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "\n\n\nLifecycle Rules:" 
 ); 
  
 for 
  
 ( 
 BucketInfo 
 . 
 LifecycleRule 
  
 rule 
  
 : 
  
 bucket 
 . 
 getLifecycleRules 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 rule 
 ); 
  
 } 
  
 } 
  
 } 
 }

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

To view a bucket's labels, follow the instructions for displaying a bucket's metadata and look for the label field in the response.

  // Imports the Google Cloud client library 
 const 
  
 { 
 Storage 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/storage 
' 
 ); 
 // Creates a client 
 const 
  
 storage 
  
 = 
  
 new 
  
 Storage 
 (); 
 async 
  
 function 
  
 getBucketMetadata 
 () 
  
 { 
  
 /** 
 * TODO(developer): Uncomment the following lines before running the sample. 
 */ 
  
 // The ID of your GCS bucket 
  
 // const bucketName = 'your-unique-bucket-name'; 
  
 // Get Bucket Metadata 
  
 const 
  
 [ 
 metadata 
 ] 
  
 = 
  
 await 
  
 storage 
 . 
 bucket 
 ( 
 bucketName 
 ). 
 getMetadata 
 (); 
  
 console 
 . 
 log 
 ( 
  JSON 
 
 . 
 stringify 
 ( 
 metadata 
 , 
  
 null 
 , 
  
 2 
 )); 
 }

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

To view a bucket's labels, follow the instructions for displaying a bucket's metadata and look for the label field in the response.

  use Google\Cloud\Storage\StorageClient; 
 /** 
 * Get bucket metadata. 
 * 
 * @param string $bucketName The name of your Cloud Storage bucket. 
 *        (e.g. 'my-bucket') 
 */ 
 function get_bucket_metadata(string $bucketName): void 
 { 
 $storage = new StorageClient(); 
 $bucket = $storage->bucket($bucketName); 
 $info = $bucket->info(); 
 printf('Bucket Metadata: %s' . PHP_EOL, print_r($info, true)); 
 }

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

To view a bucket's labels, follow the instructions for displaying a bucket's metadata and look for the label field in the response.

  from 
  
 google.cloud 
  
 import 
  storage 
 
 def 
  
 bucket_metadata 
 ( 
 bucket_name 
 ): 
  
 """Prints out a bucket's metadata.""" 
 # bucket_name = 'your-bucket-name' 
 storage_client 
 = 
  storage 
 
 . 
  Client 
 
 () 
 bucket 
 = 
 storage_client 
 . 
  get_bucket 
 
 ( 
 bucket_name 
 ) 
 print 
 ( 
 f 
 "ID: 
 { 
 bucket 
 . 
 id 
 } 
 " 
 ) 
 print 
 ( 
 f 
 "Name: 
 { 
 bucket 
 . 
 name 
 } 
 " 
 ) 
 print 
 ( 
 f 
 "Storage Class: 
 { 
 bucket 
 . 
 storage_class 
 } 
 " 
 ) 
 print 
 ( 
 f 
 "Location: 
 { 
 bucket 
 . 
  location 
 
 } 
 " 
 ) 
 print 
 ( 
 f 
 "Location Type: 
 { 
 bucket 
 . 
  location_type 
 
 } 
 " 
 ) 
 print 
 ( 
 f 
 "Cors: 
 { 
 bucket 
 . 
  cors 
 
 } 
 " 
 ) 
 print 
 ( 
 f 
 "Default Event Based Hold: 
 { 
 bucket 
 . 
  default_event_based_hold 
 
 } 
 " 
 ) 
 print 
 ( 
 f 
 "Default KMS Key Name: 
 { 
 bucket 
 . 
  default_kms_key_name 
 
 } 
 " 
 ) 
 print 
 ( 
 f 
 "Metageneration: 
 { 
 bucket 
 . 
 metageneration 
 } 
 " 
 ) 
 print 
 ( 
 f 
 "Public Access Prevention: 
 { 
 bucket 
 . 
  iam_configuration 
 
 . 
  public_access_prevention 
 
 } 
 " 
 ) 
 print 
 ( 
 f 
 "Retention Effective Time: 
 { 
 bucket 
 . 
  retention_policy_effective_time 
 
 } 
 " 
 ) 
 print 
 ( 
 f 
 "Retention Period: 
 { 
 bucket 
 . 
  retention_period 
 
 } 
 " 
 ) 
 print 
 ( 
 f 
 "Retention Policy Locked: 
 { 
 bucket 
 . 
  retention_policy_locked 
 
 } 
 " 
 ) 
 print 
 ( 
 f 
 "Object Retention Mode: 
 { 
 bucket 
 . 
  object_retention_mode 
 
 } 
 " 
 ) 
 print 
 ( 
 f 
 "Requester Pays: 
 { 
 bucket 
 . 
  requester_pays 
 
 } 
 " 
 ) 
 print 
 ( 
 f 
 "Self Link: 
 { 
 bucket 
 . 
 self_link 
 } 
 " 
 ) 
 print 
 ( 
 f 
 "Time Created: 
 { 
 bucket 
 . 
 time_created 
 } 
 " 
 ) 
 print 
 ( 
 f 
 "Versioning Enabled: 
 { 
 bucket 
 . 
  versioning_enabled 
 
 } 
 " 
 ) 
 print 
 ( 
 f 
 "Labels: 
 { 
 bucket 
 . 
  labels 
 
 } 
 " 
 )

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

To view a bucket's labels, follow the instructions for displaying a bucket's metadata and look for the label field in the response.

  def 
  
 get_bucket_metadata 
  
 bucket_name 
 : 
  
 # The ID of your GCS bucket 
  
 # bucket_name = "your-unique-bucket-name" 
  
 require 
  
 "google/cloud/storage" 
  
 storage 
  
 = 
  
 Google 
 :: 
 Cloud 
 :: 
  Storage 
 
 . 
  new 
 
  
 bucket 
  
 = 
  
 storage 
 . 
 bucket 
  
 bucket_name 
  
 puts 
  
 "ID: 
 #{ 
 bucket 
 . 
 id 
 } 
 " 
  
 puts 
  
 "Name: 
 #{ 
 bucket 
 . 
 name 
 } 
 " 
  
 puts 
  
 "Storage Class: 
 #{ 
 bucket 
 . 
 storage_class 
 } 
 " 
  
 puts 
  
 "Location: 
 #{ 
 bucket 
 . 
 location 
 } 
 " 
  
 puts 
  
 "Location Type: 
 #{ 
 bucket 
 . 
 location_type 
 } 
 " 
  
 puts 
  
 "Cors: 
 #{ 
 bucket 
 . 
 cors 
 } 
 " 
  
 puts 
  
 "Default Event Based Hold: 
 #{ 
 bucket 
 . 
  default_event_based_hold? 
 
 } 
 " 
  
 puts 
  
 "Default KMS Key Name: 
 #{ 
 bucket 
 . 
  default_kms_key 
 
 } 
 " 
  
 puts 
  
 "Logging Bucket: 
 #{ 
 bucket 
 . 
  logging_bucket 
 
 } 
 " 
  
 puts 
  
 "Logging Prefix: 
 #{ 
 bucket 
 . 
  logging_prefix 
 
 } 
 " 
  
 puts 
  
 "Metageneration: 
 #{ 
 bucket 
 . 
 metageneration 
 } 
 " 
  
 puts 
  
 "Retention Effective Time: 
 #{ 
 bucket 
 . 
  retention_effective_at 
 
 } 
 " 
  
 puts 
  
 "Retention Period: 
 #{ 
 bucket 
 . 
  retention_period 
 
 } 
 " 
  
 puts 
  
 "Retention Policy Locked: 
 #{ 
 bucket 
 . 
  retention_policy_locked? 
 
 } 
 " 
  
 puts 
  
 "Requester Pays: 
 #{ 
 bucket 
 . 
  requester_pays 
 
 } 
 " 
  
 puts 
  
 "Self Link: 
 #{ 
 bucket 
 . 
 api_url 
 } 
 " 
  
 puts 
  
 "Time Created: 
 #{ 
 bucket 
 . 
 created_at 
 } 
 " 
  
 puts 
  
 "Versioning Enabled: 
 #{ 
 bucket 
 . 
  versioning? 
 
 } 
 " 
  
 puts 
  
 "Index Page: 
 #{ 
 bucket 
 . 
  website_main 
 
 } 
 " 
  
 puts 
  
 "Not Found Page: 
 #{ 
 bucket 
 . 
  website_404 
 
 } 
 " 
  
 puts 
  
 "Labels:" 
  
 bucket 
 . 
 labels 
 . 
  each 
 
  
 do 
  
 | 
 key 
 , 
  
 value 
 | 
  
 puts 
  
 " - 
 #{ 
 key 
 } 
 = 
 #{ 
 value 
 } 
 " 
  
 end 
  
 puts 
  
 "Lifecycle Rules:" 
  
 bucket 
 . 
 lifecycle 
 . 
  each 
 
  
 do 
  
 | 
 rule 
 | 
  
 puts 
  
 " 
 #{ 
 rule 
 . 
  action 
 
 } 
 - 
 #{ 
 rule 
 . 
 storage_class 
 } 
 - 
 #{ 
 rule 
 . 
  age 
 
 } 
 - 
 #{ 
 rule 
 . 
  matches_storage_class 
 
 } 
 " 
  
 end 
 end

What's next

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License , and code samples are licensed under the Apache 2.0 License . For details, see the Google Developers Site Policies . Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-10-30 UTC.

Using bucket labels

Required roles

Required permissions

Add, modify, or remove a bucket's labels

Console

Command line

Client libraries

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

REST APIs

JSON API

XML API

View bucket labels

Console

Command line

Client libraries

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

REST APIs

JSON API

XML API

What's next