Console
    Contact Us Start free

    Use and lock retention policies

    Overview

    This page describes how to use the Bucket Lock feature, including working with retention policies and permanently locking them on buckets.

    Before you begin

    Before you can use the Bucket Lock feature, make sure the steps in the following sections have been completed.

    Get required roles

    To get the permissions that you need to use Bucket Lock, ask your administrator to grant you the Storage Admin ( roles/storage.admin ) role on the bucket. This predefined role contains the permissions required to use Bucket Lock. To see the exact permissions 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 information about granting roles on buckets, see Use IAM with buckets .

    Set a retention policy on a bucket

    To add, modify, or remove a retention policy on a bucket:

    Console

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

      Go to Buckets

    2. In the list of buckets, click the name of the bucket whose retention policy you want to change.

    3. Select the Protectiontab near the top of the page.

    4. In the Retention policysection, set your retention policy:

      1. If no retention policy currently applies to the bucket, click the Set Retention Policylink. Choose a unit of time and a length of time for your retention period.

      2. If a retention policy currently applies to a bucket, it appears in the section. Click Editto modify the retention time or Deleteto remove the retention policy entirely.

      See Retention periods for information about how the Google Cloud console converts between different units of time.

    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 update command with the appropriate flag:

    gcloud storage buckets update gs:// BUCKET_NAME 
 FLAG

    Where:

    • BUCKET_NAME is the name of the relevant bucket. For example, my-bucket .

    • FLAG is the desired setting for the bucket's retention period. Use one of the following formats:

      • --retention-period and a retention period , if you want to add or change a retention policy. For example, --retention-period=1d43200s .
      • --clear-retention-period , if you want to remove the retention policy on the bucket.

    If successful, the response looks like:

    Updating gs://my-bucket/...
  Completed 1

    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 sets a retention policy on a bucket:

      namespace 
  
 gcs 
  
 = 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 storage 
 ; 
 using 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 StatusOr 
 ; 
 []( 
 gcs 
 :: 
 Client 
  
 client 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 bucket_name 
 , 
  
 std 
 :: 
 chrono 
 :: 
 seconds 
  
 period 
 ) 
  
 { 
  
 StatusOr<gcs 
 :: 
 BucketMetadata 
>  
 original 
  
 = 
  
 client 
 . 
 GetBucketMetadata 
 ( 
 bucket_name 
 ); 
  
 if 
  
 ( 
 ! 
 original 
 ) 
  
 throw 
  
 std 
 :: 
 move 
 ( 
 original 
 ). 
 status 
 (); 
  
 StatusOr<gcs 
 :: 
 BucketMetadata 
>  
 patched 
  
 = 
  
 client 
 . 
 PatchBucket 
 ( 
  
 bucket_name 
 , 
  
 gcs 
 :: 
 BucketMetadataPatchBuilder 
 (). 
 SetRetentionPolicy 
 ( 
 period 
 ), 
  
 gcs 
 :: 
 IfMetagenerationMatch 
 ( 
 original 
 - 
> metageneration 
 ())); 
  
 if 
  
 ( 
 ! 
 patched 
 ) 
  
 throw 
  
 std 
 :: 
 move 
 ( 
 patched 
 ). 
 status 
 (); 
  
 if 
  
 ( 
 ! 
 patched 
 - 
> has_retention_policy 
 ()) 
  
 { 
  
 std 
 :: 
 cout 
 << 
 "The bucket " 
 << 
 patched 
 - 
> name 
 () 
 << 
 " does not have a retention policy set. 
 \n 
 " 
 ; 
  
 return 
 ; 
  
 } 
  
 std 
 :: 
 cout 
 << 
 "The bucket " 
 << 
 patched 
 - 
> name 
 () 
 << 
 " retention policy is set to " 
 << 
 patched 
 - 
> retention_policy 
 () 
 << 
 " 
 \n 
 " 
 ; 
 }

    The following sample removes the retention policy from a bucket:

      namespace 
  
 gcs 
  
 = 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 storage 
 ; 
 using 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 StatusOr 
 ; 
 []( 
 gcs 
 :: 
 Client 
  
 client 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 bucket_name 
 ) 
  
 { 
  
 StatusOr<gcs 
 :: 
 BucketMetadata 
>  
 original 
  
 = 
  
 client 
 . 
 GetBucketMetadata 
 ( 
 bucket_name 
 ); 
  
 if 
  
 ( 
 ! 
 original 
 ) 
  
 throw 
  
 std 
 :: 
 move 
 ( 
 original 
 ). 
 status 
 (); 
  
 StatusOr<gcs 
 :: 
 BucketMetadata 
>  
 patched 
  
 = 
  
 client 
 . 
 PatchBucket 
 ( 
  
 bucket_name 
 , 
  
 gcs 
 :: 
 BucketMetadataPatchBuilder 
 (). 
 ResetRetentionPolicy 
 (), 
  
 gcs 
 :: 
 IfMetagenerationMatch 
 ( 
 original 
 - 
> metageneration 
 ())); 
  
 if 
  
 ( 
 ! 
 patched 
 ) 
  
 throw 
  
 std 
 :: 
 move 
 ( 
 patched 
 ). 
 status 
 (); 
  
 if 
  
 ( 
 ! 
 patched 
 - 
> has_retention_policy 
 ()) 
  
 { 
  
 std 
 :: 
 cout 
 << 
 "The bucket " 
 << 
 patched 
 - 
> name 
 () 
 << 
 " does not have a retention policy set. 
 \n 
 " 
 ; 
  
 return 
 ; 
  
 } 
  
 std 
 :: 
 cout 
 << 
 "The bucket " 
 << 
 patched 
 - 
> name 
 () 
 << 
 " retention policy is set to " 
 << 
 patched 
 - 
> retention_policy 
 () 
 << 
 ". This is unexpected, maybe a concurrent change by another" 
 << 
 " application? 
 \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 sets a retention policy on a bucket:

      using 
  
  Google.Cloud.Storage.V1 
 
 ; 
 using 
  
 System 
 ; 
 using 
  
 static 
  
 Google 
 . 
 Apis 
 . 
 Storage 
 . 
 v1 
 . 
 Data 
 . 
 Bucket 
 ; 
 public 
  
 class 
  
 SetRetentionPolicySample 
 { 
  
 /// <summary> 
  
 /// Sets the bucket's retention policy. 
  
 /// </summary> 
  
 /// <param name="bucketName">The name of the bucket.</param> 
  
 /// <param name="retentionPeriod">The duration in seconds that objects need to be retained. The retention policy enforces a minimum retention 
  
 /// time for all objects contained in the bucket, based on their creation time. Any 
  
 /// attempt to overwrite or delete objects younger than the retention period will 
  
 /// result in a PERMISSION_DENIED error. An unlocked retention policy can be modified 
  
 /// or removed from the bucket via a storage.buckets.update operation. A locked retention 
  
 /// policy cannot be removed or shortened in duration for the lifetime of the bucket. 
  
 /// Attempting to remove or decrease the period of a locked retention policy will result 
  
 /// in a PERMISSION_DENIED error.</param> 
  
 public 
  
 RetentionPolicyData 
  
 SetRetentionPolicy 
 ( 
  
 string 
  
 bucketName 
  
 = 
  
 "your-unique-bucket-name" 
 , 
  
 long 
  
 retentionPeriod 
  
 = 
  
 10 
 ) 
  
 { 
  
 var 
  
 storage 
  
 = 
  
  StorageClient 
 
 . 
  Create 
 
 (); 
  
 var 
  
 bucket 
  
 = 
  
 storage 
 . 
 GetBucket 
 ( 
 bucketName 
 ); 
  
 bucket 
 . 
 RetentionPolicy 
  
 = 
  
 new 
  
 RetentionPolicyData 
  
 { 
  
 RetentionPeriod 
  
 = 
  
 retentionPeriod 
  
 }; 
  
 bucket 
  
 = 
  
 storage 
 . 
 UpdateBucket 
 ( 
 bucket 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Retention policy for {bucketName} was set to {retentionPeriod}" 
 ); 
  
 return 
  
 bucket 
 . 
 RetentionPolicy 
 ; 
  
 } 
 }

    The following sample removes the retention policy from a bucket:

      using 
  
  Google.Cloud.Storage.V1 
 
 ; 
 using 
  
 System 
 ; 
 public 
  
 class 
  
 RemoveRetentionPolicySample 
 { 
  
 public 
  
 void 
  
 RemoveRetentionPolicy 
 ( 
 string 
  
 bucketName 
  
 = 
  
 "your-unique-bucket-name" 
 ) 
  
 { 
  
 var 
  
 storage 
  
 = 
  
  StorageClient 
 
 . 
  Create 
 
 (); 
  
 var 
  
 bucket 
  
 = 
  
 storage 
 . 
 GetBucket 
 ( 
 bucketName 
 ); 
  
 if 
  
 ( 
 bucket 
 . 
 RetentionPolicy 
  
 != 
  
 null 
 ) 
  
 { 
  
 bool 
  
 isLocked 
  
 = 
  
 bucket 
 . 
 RetentionPolicy 
 . 
 IsLocked 
  
 ?? 
  
 false 
 ; 
  
 if 
  
 ( 
 isLocked 
 ) 
  
 { 
  
 throw 
  
 new 
  
 Exception 
 ( 
 "Retention Policy is locked." 
 ); 
  
 } 
  
 bucket 
 . 
 RetentionPolicy 
 . 
 RetentionPeriod 
  
 = 
  
 null 
 ; 
  
 storage 
 . 
 UpdateBucket 
 ( 
 bucket 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Retention period for {bucketName} has been removed." 
 ); 
  
 } 
  
 } 
 }

    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 sets a retention policy on a bucket:

      import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 "time" 
  
 "cloud.google.com/go/storage" 
 ) 
 // setRetentionPolicy sets the bucket retention period. 
 func 
  
 setRetentionPolicy 
 ( 
 w 
  
 io 
 . 
  Writer 
 
 , 
  
 bucketName 
  
 string 
 , 
  
 retentionPeriod 
  
 time 
 . 
 Duration 
 ) 
  
 error 
  
 { 
  
 // bucketName := "bucket-name" 
  
 // retentionPeriod := time.Second 
  
 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 
 
 { 
  
 RetentionPolicy 
 : 
  
& storage 
 . 
  RetentionPolicy 
 
 { 
  
 RetentionPeriod 
 : 
  
 retentionPeriod 
 , 
  
 }, 
  
 } 
  
 if 
  
 _ 
 , 
  
 err 
  
 := 
  
 bucket 
 . 
 Update 
 ( 
 ctx 
 , 
  
 bucketAttrsToUpdate 
 ); 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "Bucket(%q).Update: %w" 
 , 
  
 bucketName 
 , 
  
 err 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Retention policy for %v was set to %v\n" 
 , 
  
 bucketName 
 , 
  
 bucketAttrsToUpdate 
 . 
  RetentionPolicy 
 
 . 
 RetentionPeriod 
 ) 
  
 return 
  
 nil 
 }

    The following sample removes the retention policy from a bucket:

      import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 "time" 
  
 "cloud.google.com/go/storage" 
 ) 
 // removeRetentionPolicy removes bucket retention policy. 
 func 
  
 removeRetentionPolicy 
 ( 
 w 
  
 io 
 . 
  Writer 
 
 , 
  
 bucketName 
  
 string 
 ) 
  
 error 
  
 { 
  
 // bucketName := "bucket-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 
 * 
 50 
 ) 
  
 defer 
  
 cancel 
 () 
  
 bucket 
  
 := 
  
 client 
 . 
  Bucket 
 
 ( 
 bucketName 
 ) 
  
 attrs 
 , 
  
 err 
  
 := 
  
 bucket 
 . 
 Attrs 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "Bucket(%q).Attrs: %w" 
 , 
  
 bucketName 
 , 
  
 err 
 ) 
  
 } 
  
 if 
  
 attrs 
 . 
  RetentionPolicy 
 
 . 
 IsLocked 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "retention policy is locked" 
 ) 
  
 } 
  
 bucketAttrsToUpdate 
  
 := 
  
 storage 
 . 
  BucketAttrsToUpdate 
 
 { 
  
 RetentionPolicy 
 : 
  
& storage 
 . 
  RetentionPolicy 
 
 {}, 
  
 } 
  
 if 
  
 _ 
 , 
  
 err 
  
 := 
  
 bucket 
 . 
 Update 
 ( 
 ctx 
 , 
  
 bucketAttrsToUpdate 
 ); 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "Bucket(%q).Update: %w" 
 , 
  
 bucketName 
 , 
  
 err 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Retention period for %v has been removed\n" 
 , 
  
 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 sets a retention policy on a bucket:

      import 
  
 com.google.cloud.storage. Bucket 
 
 ; 
 import 
  
 com.google.cloud.storage. Storage 
 
 ; 
 import 
  
 com.google.cloud.storage. Storage 
. BucketTargetOption 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageException 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageOptions 
 
 ; 
 import 
  
 java.time.Duration 
 ; 
 public 
  
 class 
 SetRetentionPolicy 
  
 { 
  
 public 
  
 static 
  
 void 
  
 setRetentionPolicy 
 ( 
  
 String 
  
 projectId 
 , 
  
 String 
  
 bucketName 
 , 
  
 Long 
  
 retentionPeriodSeconds 
 ) 
  
 throws 
  
  StorageException 
 
  
 { 
  
 // The ID of your GCP project 
  
 // String projectId = "your-project-id"; 
  
 // The ID of your GCS bucket 
  
 // String bucketName = "your-unique-bucket-name"; 
  
 // The retention period for objects in bucket 
  
 // Long retentionPeriodSeconds = 3600L; // 1 hour in seconds 
  
  Storage 
 
  
 storage 
  
 = 
  
  StorageOptions 
 
 . 
 newBuilder 
 (). 
 setProjectId 
 ( 
 projectId 
 ). 
 build 
 (). 
  getService 
 
 (); 
  
 // first look up the bucket so we will have its metageneration 
  
  Bucket 
 
  
 bucket 
  
 = 
  
 storage 
 . 
  get 
 
 ( 
 bucketName 
 ); 
  
  Bucket 
 
  
 bucketWithRetentionPolicy 
  
 = 
  
 storage 
 . 
  update 
 
 ( 
  
 bucket 
 . 
 toBuilder 
 () 
  
 . 
 setRetentionPeriodDuration 
 ( 
 Duration 
 . 
 ofSeconds 
 ( 
 retentionPeriodSeconds 
 )) 
  
 . 
 build 
 (), 
  
 BucketTargetOption 
 . 
 metagenerationMatch 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
  
 "Retention period for " 
  
 + 
  
 bucketName 
  
 + 
  
 " is now " 
  
 + 
  
 bucketWithRetentionPolicy 
 . 
  getRetentionPeriodDuration 
 
 ()); 
  
 } 
 }

    The following sample removes the retention policy from a bucket:

      import 
  
 com.google.cloud.storage. Bucket 
 
 ; 
 import 
  
 com.google.cloud.storage. Storage 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageException 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageOptions 
 
 ; 
 public 
  
 class 
 RemoveRetentionPolicy 
  
 { 
  
 public 
  
 static 
  
 void 
  
 removeRetentionPolicy 
 ( 
 String 
  
 projectId 
 , 
  
 String 
  
 bucketName 
 ) 
  
 throws 
  
  StorageException 
 
 , 
  
 IllegalArgumentException 
  
 { 
  
 // 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 
 
 (); 
  
  Bucket 
 
  
 bucket 
  
 = 
  
 storage 
 . 
  get 
 
 ( 
  
 bucketName 
 , 
  
 Storage 
 . 
 BucketGetOption 
 . 
 fields 
 ( 
 Storage 
 . 
 BucketField 
 . 
 RETENTION_POLICY 
 )); 
  
 if 
  
 ( 
 bucket 
 . 
  retentionPolicyIsLocked 
 
 () 
  
 != 
  
 null 
 && 
 bucket 
 . 
  retentionPolicyIsLocked 
 
 ()) 
  
 { 
  
 throw 
  
 new 
  
 IllegalArgumentException 
 ( 
  
 "Unable to remove retention policy as retention policy is locked." 
 ); 
  
 } 
  
 bucket 
 . 
  toBuilder 
 
 (). 
 setRetentionPeriod 
 ( 
 null 
 ). 
 build 
 (). 
 update 
 (); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Retention policy for " 
  
 + 
  
 bucketName 
  
 + 
  
 " has been removed" 
 ); 
  
 } 
 }

    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 sets a retention policy on 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 retention period for objects in bucket 
 // const retentionPeriod = 3600; // 1 hour in seconds 
 // Imports the Google Cloud client library 
 const 
  
 { 
 Storage 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/storage 
' 
 ); 
 // Creates a client 
 const 
  
 storage 
  
 = 
  
 new 
  
 Storage 
 (); 
 async 
  
 function 
  
 setRetentionPolicy 
 () 
  
 { 
  
 const 
  
 [ 
 metadata 
 ] 
  
 = 
  
 await 
  
 storage 
  
 . 
 bucket 
 ( 
 bucketName 
 ) 
  
 . 
  setRetentionPeriod 
 
 ( 
 retentionPeriod 
 ); 
  
 console 
 . 
 log 
 ( 
  
 `Bucket 
 ${ 
 bucketName 
 } 
 retention period set for 
 ${ 
 metadata 
 . 
  retentionPolicy 
 
 . 
 retentionPeriod 
 } 
 seconds.` 
  
 ); 
 } 
 setRetentionPolicy 
 (). 
 catch 
 ( 
 console 
 . 
 error 
 );

    The following sample removes the retention policy 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'; 
 // Imports the Google Cloud client library 
 const 
  
 { 
 Storage 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/storage 
' 
 ); 
 // Creates a client 
 const 
  
 storage 
  
 = 
  
 new 
  
 Storage 
 (); 
 async 
  
 function 
  
 removeRetentionPolicy 
 () 
  
 { 
  
 const 
  
 [ 
 metadata 
 ] 
  
 = 
  
 await 
  
 storage 
 . 
 bucket 
 ( 
 bucketName 
 ). 
 getMetadata 
 (); 
  
 if 
  
 ( 
 metadata 
 . 
  retentionPolicy 
 
 && 
 metadata 
 . 
  retentionPolicy 
 
 . 
 isLocked 
 ) 
  
 { 
  
 console 
 . 
 log 
 ( 
  
 'Unable to remove retention period as retention policy is locked.' 
  
 ); 
  
 return 
  
 null 
 ; 
  
 } 
  
 else 
  
 { 
  
 const 
  
 results 
  
 = 
  
 await 
  
 storage 
 . 
 bucket 
 ( 
 bucketName 
 ). 
  removeRetentionPeriod 
 
 (); 
  
 console 
 . 
 log 
 ( 
 `Removed bucket 
 ${ 
 bucketName 
 } 
 retention policy.` 
 ); 
  
 return 
  
 results 
 ; 
  
 } 
 } 
 removeRetentionPolicy 
 (). 
 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 sets a retention policy on a bucket:

      use Google\Cloud\Storage\StorageClient; 
 /** 
 * Sets a bucket's retention policy. 
 * 
 * @param string $bucketName The name of your Cloud Storage bucket. 
 *        (e.g. 'my-bucket') 
 * @param int $retentionPeriod The retention period for objects in bucket, in seconds. 
 *        (e.g. 3600) 
 */ 
 function set_retention_policy(string $bucketName, int $retentionPeriod): void 
 { 
 $storage = new StorageClient(); 
 $bucket = $storage->bucket($bucketName); 
 $bucket->update([ 
 'retentionPolicy' => [ 
 'retentionPeriod' => $retentionPeriod 
 ]]); 
 printf('Bucket %s retention period set to %s seconds' . PHP_EOL, $bucketName, 
 $retentionPeriod); 
 }

    The following sample removes the retention policy from a bucket:

      use Google\Cloud\Storage\StorageClient; 
 /** 
 * Removes a bucket's retention policy. 
 * 
 * @param string $bucketName The name of your Cloud Storage bucket. 
 *        (e.g. 'my-bucket') 
 */ 
 function remove_retention_policy(string $bucketName): void 
 { 
 $storage = new StorageClient(); 
 $bucket = $storage->bucket($bucketName); 
 $bucket->reload(); 
 if (array_key_exists('isLocked', $bucket->info()['retentionPolicy']) 
&& $bucket->info()['retentionPolicy']['isLocked']) { 
 printf('Unable to remove retention period as retention policy is locked.' . PHP_EOL); 
 return; 
 } 
 $bucket->update([ 
 'retentionPolicy' => [] 
 ]); 
 printf('Removed bucket %s retention policy' . PHP_EOL, $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 sets a retention policy on a bucket:

      from 
  
 google.cloud 
  
 import 
  storage 
 
 def 
  
 set_retention_policy 
 ( 
 bucket_name 
 , 
 retention_period 
 ): 
  
 """Defines a retention policy on a given bucket""" 
 # bucket_name = "my-bucket" 
 # retention_period = 10 
 storage_client 
 = 
  storage 
 
 . 
  Client 
 
 () 
 bucket 
 = 
 storage_client 
 . 
  bucket 
 
 ( 
 bucket_name 
 ) 
 bucket 
 . 
  retention_period 
 
 = 
 retention_period 
 bucket 
 . 
 patch 
 () 
 print 
 ( 
 "Bucket 
 {} 
 retention period set for 
 {} 
 seconds" 
 . 
 format 
 ( 
 bucket 
 . 
 name 
 , 
 bucket 
 . 
  retention_period 
 
 ) 
 )

    The following sample removes the retention policy from a bucket:

      from 
  
 google.cloud 
  
 import 
  storage 
 
 def 
  
 remove_retention_policy 
 ( 
 bucket_name 
 ): 
  
 """Removes the retention policy on a given bucket""" 
 # bucket_name = "my-bucket" 
 storage_client 
 = 
  storage 
 
 . 
  Client 
 
 () 
 bucket 
 = 
 storage_client 
 . 
  bucket 
 
 ( 
 bucket_name 
 ) 
 bucket 
 . 
 reload 
 () 
 if 
 bucket 
 . 
  retention_policy_locked 
 
 : 
 print 
 ( 
 "Unable to remove retention period as retention policy is locked." 
 ) 
 return 
 bucket 
 . 
  retention_period 
 
 = 
 None 
 bucket 
 . 
 patch 
 () 
 print 
 ( 
 f 
 "Removed bucket 
 { 
 bucket 
 . 
 name 
 } 
 retention policy" 
 )

    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 sets a retention policy on a bucket:

      def 
  
 set_retention_policy 
  
 bucket_name 
 :, 
  
 retention_period 
 : 
  
 # The ID of your GCS bucket 
  
 # bucket_name = "your-unique-bucket-name" 
  
 # The retention period for objects in bucket 
  
 # retention_period = 3600 # 1 hour in seconds 
  
 require 
  
 "google/cloud/storage" 
  
 storage 
  
 = 
  
 Google 
 :: 
 Cloud 
 :: 
  Storage 
 
 . 
  new 
 
  
 bucket 
  
 = 
  
 storage 
 . 
 bucket 
  
 bucket_name 
  
 bucket 
 . 
  retention_period 
 
  
 = 
  
 retention_period 
  
 puts 
  
 "Retention period for 
 #{ 
 bucket_name 
 } 
 is now 
 #{ 
 bucket 
 . 
  retention_period 
 
 } 
 seconds." 
 end

    The following sample removes the retention policy from a bucket:

      def 
  
 remove_retention_policy 
  
 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 
  
 if 
  
 ! 
 bucket 
 . 
  retention_policy_locked? 
 
  
 bucket 
 . 
  retention_period 
 
  
 = 
  
 nil 
  
 puts 
  
 "Retention policy for 
 #{ 
 bucket_name 
 } 
 has been removed." 
  
 else 
  
 puts 
  
 "Policy is locked and retention policy can't be removed." 
  
 end 
 end

    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:

       { 
  
 "retentionPolicy" 
 : 
  
 { 
  
 "retentionPeriod" 
 : 
  
 " TIME_IN_SECONDS 
" 
  
 } 
 }

      Where TIME_IN_SECONDS is the amount of time in seconds that objects in the bucket must be retained. For example, 2678400 . See Retention periods for information about how different units of time are measured using seconds.

      To remove the retention policy from a bucket, use the following in the JSON file:

       { 
  
 "retentionPolicy" 
 : 
  
 null 
 }

    3. Use cURL to call the JSON API with a PATCH Bucket 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 
?fields=retentionPolicy"

      Where:

      • JSON_FILE_NAME is the path for the JSON file that you created in Step 2.
      • BUCKET_NAME is the name of the relevant bucket. For example, my-bucket .

    XML API

    The XML API cannot be used to set or remove a retention policy on an existing bucket. It can only be used to include a retention policy with a new bucket .

    Lock a bucket

    To lock a bucket and permanently restrict edits to the bucket's retention policy:

    Console

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

      Go to Buckets

    2. In the list of buckets, click the name of the bucket that you want to lock the retention policy for.

    3. Select the Protectiontab near the top of the page.

    4. In the Retention policysection, click the Lockbutton.

      The Lock retention policy?dialog box appears.

    5. Read the Permanentnotice.

    6. In the Bucket nametext box, type in the name of your bucket.

    7. Click Lock policy.

    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 update command with the --lock-retention-period flag:

    gcloud storage buckets update gs:// BUCKET_NAME 
--lock-retention-period

    Where BUCKET_NAME is the name of the relevant bucket. For example, my-bucket .

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

    Updating gs://my-bucket/...
  Completed 1

    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 .

      namespace 
  
 gcs 
  
 = 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 storage 
 ; 
 using 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 StatusOr 
 ; 
 []( 
 gcs 
 :: 
 Client 
  
 client 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 bucket_name 
 ) 
  
 { 
  
 StatusOr<gcs 
 :: 
 BucketMetadata 
>  
 original 
  
 = 
  
 client 
 . 
 GetBucketMetadata 
 ( 
 bucket_name 
 ); 
  
 if 
  
 ( 
 ! 
 original 
 ) 
  
 throw 
  
 std 
 :: 
 move 
 ( 
 original 
 ). 
 status 
 (); 
  
 StatusOr<gcs 
 :: 
 BucketMetadata 
>  
 updated_metadata 
  
 = 
  
 client 
 . 
 LockBucketRetentionPolicy 
 ( 
 bucket_name 
 , 
  
 original 
 - 
> metageneration 
 ()); 
  
 if 
  
 ( 
 ! 
 updated_metadata 
 ) 
  
 throw 
  
 std 
 :: 
 move 
 ( 
 updated_metadata 
 ). 
 status 
 (); 
  
 if 
  
 ( 
 ! 
 updated_metadata 
 - 
> has_retention_policy 
 ()) 
  
 { 
  
 std 
 :: 
 cerr 
 << 
 "The bucket " 
 << 
 updated_metadata 
 - 
> name 
 () 
 << 
 " does not have a retention policy, even though the" 
 << 
 " operation to set it was successful. 
 \n 
 " 
 << 
 "This is unexpected, and may indicate that another" 
 << 
 " application has modified the bucket concurrently. 
 \n 
 " 
 ; 
  
 return 
 ; 
  
 } 
  
 std 
 :: 
 cout 
 << 
 "Retention policy successfully locked for bucket " 
 << 
 updated_metadata 
 - 
> name 
 () 
 << 
 " 
 \n 
 New retention policy is: " 
 << 
 updated_metadata 
 - 
> retention_policy 
 () 
 << 
 " 
 \n 
 Full metadata: " 
 << 
 * 
 updated_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 .

      using 
  
  Google.Cloud.Storage.V1 
 
 ; 
 using 
  
 System 
 ; 
 public 
  
 class 
  
 LockRetentionPolicySample 
 { 
  
 /// <summary> 
  
 /// Locks the retention policy of a bucket. This is a one-way process: once a retention 
  
 /// policy is locked, it cannot be shortened, removed or unlocked, although it can 
  
 /// be increased in duration. The lock persists until the bucket is deleted. 
  
 /// </summary> 
  
 /// <param name="bucketName">The name of the bucket whose retention policy should be locked.</param> 
  
 public 
  
 bool? 
  
 LockRetentionPolicy 
 ( 
 string 
  
 bucketName 
  
 = 
  
 "your-unique-bucket-name" 
 ) 
  
 { 
  
 var 
  
 storage 
  
 = 
  
  StorageClient 
 
 . 
  Create 
 
 (); 
  
 var 
  
 bucket 
  
 = 
  
 storage 
 . 
 GetBucket 
 ( 
 bucketName 
 ); 
  
 storage 
 . 
 LockBucketRetentionPolicy 
 ( 
 bucketName 
 , 
  
 bucket 
 . 
 Metageneration 
 . 
 Value 
 ); 
  
 bucket 
  
 = 
  
 storage 
 . 
 GetBucket 
 ( 
 bucketName 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Retention policy for {bucketName} is now locked" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Retention policy effective as of {bucket.RetentionPolicy.EffectiveTime}" 
 ); 
  
 return 
  
 bucket 
 . 
 RetentionPolicy 
 . 
 IsLocked 
 ; 
  
 } 
 }

    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 .

      import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 "time" 
  
 "cloud.google.com/go/storage" 
 ) 
 // lockRetentionPolicy locks bucket retention policy. 
 func 
  
 lockRetentionPolicy 
 ( 
 w 
  
 io 
 . 
  Writer 
 
 , 
  
 bucketName 
  
 string 
 ) 
  
 error 
  
 { 
  
 // bucketName := "bucket-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 
 * 
 50 
 ) 
  
 defer 
  
 cancel 
 () 
  
 bucket 
  
 := 
  
 client 
 . 
  Bucket 
 
 ( 
 bucketName 
 ) 
  
 attrs 
 , 
  
 err 
  
 := 
  
 bucket 
 . 
 Attrs 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "Bucket(%q).Attrs: %w" 
 , 
  
 bucketName 
 , 
  
 err 
 ) 
  
 } 
  
 conditions 
  
 := 
  
 storage 
 . 
  BucketConditions 
 
 { 
  
 MetagenerationMatch 
 : 
  
 attrs 
 . 
 MetaGeneration 
 , 
  
 } 
  
 if 
  
 err 
  
 := 
  
 bucket 
 . 
 If 
 ( 
 conditions 
 ). 
  LockRetentionPolicy 
 
 ( 
 ctx 
 ); 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "Bucket(%q).LockRetentionPolicy: %w" 
 , 
  
 bucketName 
 , 
  
 err 
 ) 
  
 } 
  
 lockedAttrs 
 , 
  
 err 
  
 := 
  
 bucket 
 . 
 Attrs 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "Bucket(%q).Attrs: lockedAttrs: %w" 
 , 
  
 bucketName 
 , 
  
 err 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Retention policy for %v is now locked\n" 
 , 
  
 bucketName 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Retention policy effective as of %v\n" 
 , 
  
 lockedAttrs 
 . 
  RetentionPolicy 
 
 . 
 EffectiveTime 
 ) 
  
 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 .

      import 
  
 com.google.cloud.storage. Bucket 
 
 ; 
 import 
  
 com.google.cloud.storage. Storage 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageException 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageOptions 
 
 ; 
 import 
  
 java.util.Date 
 ; 
 public 
  
 class 
 LockRetentionPolicy 
  
 { 
  
 public 
  
 static 
  
 void 
  
 lockRetentionPolicy 
 ( 
 String 
  
 projectId 
 , 
  
 String 
  
 bucketName 
 ) 
  
 throws 
  
  StorageException 
 
  
 { 
  
 // 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 
 
 (); 
  
  Bucket 
 
  
 bucket 
  
 = 
  
 storage 
 . 
  get 
 
 ( 
 bucketName 
 , 
  
 Storage 
 . 
 BucketGetOption 
 . 
 fields 
 ( 
 Storage 
 . 
 BucketField 
 . 
 METAGENERATION 
 )); 
  
  Bucket 
 
  
 lockedBucket 
  
 = 
  
 bucket 
 . 
  lockRetentionPolicy 
 
 ( 
 Storage 
 . 
 BucketTargetOption 
 . 
 metagenerationMatch 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Retention period for " 
  
 + 
  
 bucketName 
  
 + 
  
 " is now locked" 
 ); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
  
 "Retention policy effective as of " 
  
 + 
  
 new 
  
 Date 
 ( 
 lockedBucket 
 . 
  getRetentionEffectiveTime 
 
 ())); 
  
 } 
 }

    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 .

      /** 
 * TODO(developer): Uncomment the following lines before running the sample. 
 */ 
 // The ID of your GCS bucket 
 // const bucketName = 'your-unique-bucket-name'; 
 // Imports the Google Cloud client library 
 const 
  
 { 
 Storage 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/storage 
' 
 ); 
 // Creates a client 
 const 
  
 storage 
  
 = 
  
 new 
  
 Storage 
 (); 
 async 
  
 function 
  
 lockRetentionPolicy 
 () 
  
 { 
  
 // Gets the current metageneration value for the bucket, required by 
  
 // lock_retention_policy 
  
 const 
  
 [ 
 unlockedMetadata 
 ] 
  
 = 
  
 await 
  
 storage 
 . 
 bucket 
 ( 
 bucketName 
 ). 
 getMetadata 
 (); 
  
 // Warning: Once a retention policy is locked, it cannot be unlocked. The 
  
 // retention period can only be increased 
  
 const 
  
 [ 
 lockedMetadata 
 ] 
  
 = 
  
 await 
  
 storage 
  
 . 
 bucket 
 ( 
 bucketName 
 ) 
  
 . 
  lock 
 
 ( 
 unlockedMetadata 
 . 
 metageneration 
 ); 
  
 console 
 . 
 log 
 ( 
 `Retention policy for 
 ${ 
 bucketName 
 } 
 is now locked` 
 ); 
  
 console 
 . 
 log 
 ( 
  
 `Retention policy effective as of 
 ${ 
 lockedMetadata 
 . 
  retentionPolicy 
 
 . 
 effectiveTime 
 } 
 ` 
  
 ); 
  
 return 
  
 lockedMetadata 
 ; 
 } 
 lockRetentionPolicy 
 (). 
 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 .

      use Google\Cloud\Storage\StorageClient; 
 /** 
 * Locks a bucket's retention policy. 
 * 
 * @param string $bucketName The name of your Cloud Storage bucket. 
 *        (e.g. 'my-bucket') 
 */ 
 function lock_retention_policy(string $bucketName): void 
 { 
 $storage = new StorageClient(); 
 $bucket = $storage->bucket($bucketName); 
 $bucket->reload(); 
 $bucket->lockRetentionPolicy(); 
 printf('Bucket %s retention policy locked' . PHP_EOL, $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 .

      from 
  
 google.cloud 
  
 import 
  storage 
 
 def 
  
 lock_retention_policy 
 ( 
 bucket_name 
 ): 
  
 """Locks the retention policy on a given bucket""" 
 # bucket_name = "my-bucket" 
 storage_client 
 = 
  storage 
 
 . 
  Client 
 
 () 
 # get_bucket gets the current metageneration value for the bucket, 
 # required by lock_retention_policy. 
 bucket 
 = 
 storage_client 
 . 
  get_bucket 
 
 ( 
 bucket_name 
 ) 
 # Warning: Once a retention policy is locked it cannot be unlocked 
 # and retention period can only be increased. 
 bucket 
 . 
  lock_retention_policy 
 
 () 
 print 
 ( 
 f 
 "Retention policy for 
 { 
 bucket_name 
 } 
 is now locked" 
 ) 
 print 
 ( 
 f 
 "Retention policy effective as of 
 { 
 bucket 
 . 
  retention_policy_effective_time 
 
 } 
 " 
 )

    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 .

      def 
  
 lock_retention_policy 
  
 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 
  
 # Warning: Once a retention policy is locked it cannot be unlocked 
  
 # and retention period can only be increased. 
  
 # Uses Bucket#metageneration as a precondition. 
  
 bucket 
 . 
  lock_retention_policy! 
 
  
 puts 
  
 "Retention policy for 
 #{ 
 bucket_name 
 } 
 is now locked." 
  
 puts 
  
 "Retention policy effective as of 
 #{ 
 bucket 
 . 
  retention_effective_at 
 
 } 
 ." 
 end

    REST APIs

    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 POST Bucket request:

      curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/ BUCKET_NAME 
/lockRetentionPolicy?ifMetagenerationMatch= BUCKET_METAGENERATION_NUMBER 
"

      Where:

      • BUCKET_NAME is the name of the relevant bucket. For example, my-bucket .
      • BUCKET_METAGENERATION_NUMBER is the metageneration value for the bucket. For example, 8 . You can find the metageneration value for your bucket by calling the JSON API with a GET Bucket request.

    XML API

    The XML API cannot be used to lock a bucket. Use one of the other Cloud Storage tools, such as the Google Cloud console, instead.

    View a bucket's retention policy and lock status

    To view what, if any, retention policy is set on a bucket and whether that retention policy is locked:

    Console

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

      Go to Buckets

    2. Click the name of the bucket whose status you want to view.

      If a bucket has a retention policy, the retention period is displayed in the Protectionfield for the bucket. If the retention policy is not locked, a lock icon appears next to the retention period in an unlocked state. If the retention policy is locked, a lock icon appears next to the retention period in a locked state.

    Command line

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

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

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

    If successful and a retention policy exists for the bucket, the response is similar to the following:

    retention_policy:
  effectiveTime: '2022-10-04T18:51:22.161000+00:00'
  retentionPeriod: '129600'

    If successful and a retention policy does 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 .

      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 
 (); 
  
 if 
  
 ( 
 ! 
 bucket_metadata 
 - 
> has_retention_policy 
 ()) 
  
 { 
  
 std 
 :: 
 cout 
 << 
 "The bucket " 
 << 
 bucket_metadata 
 - 
> name 
 () 
 << 
 " does not have a retention policy set. 
 \n 
 " 
 ; 
  
 return 
 ; 
  
 } 
  
 std 
 :: 
 cout 
 << 
 "The bucket " 
 << 
 bucket_metadata 
 - 
> name 
 () 
 << 
 " retention policy is set to " 
 << 
 bucket_metadata 
 - 
> retention_policy 
 () 
 << 
 " 
 \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 .

      using 
  
  Google.Cloud.Storage.V1 
 
 ; 
 using 
  
 System 
 ; 
 using 
  
 static 
  
 Google 
 . 
 Apis 
 . 
 Storage 
 . 
 v1 
 . 
 Data 
 . 
 Bucket 
 ; 
 public 
  
 class 
  
 GetRetentionPolicySample 
 { 
  
 public 
  
 RetentionPolicyData 
  
 GetRetentionPolicy 
 ( 
 string 
  
 bucketName 
  
 = 
  
 "your-unique-bucket-name" 
 ) 
  
 { 
  
 var 
  
 storage 
  
 = 
  
  StorageClient 
 
 . 
  Create 
 
 (); 
  
 var 
  
 bucket 
  
 = 
  
 storage 
 . 
 GetBucket 
 ( 
 bucketName 
 ); 
  
 if 
  
 ( 
 bucket 
 . 
 RetentionPolicy 
  
 != 
  
 null 
 ) 
  
 { 
  
 Console 
 . 
 WriteLine 
 ( 
 "Retention policy:" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Period: {bucket.RetentionPolicy.RetentionPeriod}" 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Effective time: {bucket.RetentionPolicy.EffectiveTime}" 
 ); 
  
 bool 
  
 isLocked 
  
 = 
  
 bucket 
 . 
 RetentionPolicy 
 . 
 IsLocked 
  
 ?? 
  
 false 
 ; 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Policy locked: {isLocked}" 
 ); 
  
 } 
  
 return 
  
 bucket 
 . 
 RetentionPolicy 
 ; 
  
 } 
 }

    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 .

      import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 "time" 
  
 "cloud.google.com/go/storage" 
 ) 
 // getRetentionPolicy gets bucket retention policy. 
 func 
  
 getRetentionPolicy 
 ( 
 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 
 ) 
  
 } 
  
 if 
  
 attrs 
 . 
  RetentionPolicy 
 
  
 != 
  
 nil 
  
 { 
  
 fmt 
 . 
 Fprintln 
 ( 
 w 
 , 
  
 "Retention Policy" 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "period: %v\n" 
 , 
  
 attrs 
 . 
  RetentionPolicy 
 
 . 
 RetentionPeriod 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "effective time: %v\n" 
 , 
  
 attrs 
 . 
  RetentionPolicy 
 
 . 
 EffectiveTime 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "policy locked: %v\n" 
 , 
  
 attrs 
 . 
  RetentionPolicy 
 
 . 
 IsLocked 
 ) 
  
 } 
  
 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 .

      import 
  
 com.google.cloud.storage. Bucket 
 
 ; 
 import 
  
 com.google.cloud.storage. Storage 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageException 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageOptions 
 
 ; 
 import 
  
 java.util.Date 
 ; 
 public 
  
 class 
 GetRetentionPolicy 
  
 { 
  
 public 
  
 static 
  
 void 
  
 getRetentionPolicy 
 ( 
 String 
  
 projectId 
 , 
  
 String 
  
 bucketName 
 ) 
  
 throws 
  
  StorageException 
 
  
 { 
  
 // 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 
 
 (); 
  
  Bucket 
 
  
 bucket 
  
 = 
  
 storage 
 . 
  get 
 
 ( 
  
 bucketName 
 , 
  
 Storage 
 . 
 BucketGetOption 
 . 
 fields 
 ( 
 Storage 
 . 
 BucketField 
 . 
 RETENTION_POLICY 
 )); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Retention Policy for " 
  
 + 
  
 bucketName 
 ); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Retention Period: " 
  
 + 
  
 bucket 
 . 
  getRetentionPeriod 
 
 ()); 
  
 if 
  
 ( 
 bucket 
 . 
  retentionPolicyIsLocked 
 
 () 
  
 != 
  
 null 
 && 
 bucket 
 . 
  retentionPolicyIsLocked 
 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Retention Policy is locked" 
 ); 
  
 } 
  
 if 
  
 ( 
 bucket 
 . 
  getRetentionEffectiveTime 
 
 () 
  
 != 
  
 null 
 ) 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Effective Time: " 
  
 + 
  
 new 
  
 Date 
 ( 
 bucket 
 . 
  getRetentionEffectiveTime 
 
 ())); 
  
 } 
  
 } 
 }

    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 .

      /** 
 * TODO(developer): Uncomment the following lines before running the sample. 
 */ 
 // The ID of your GCS bucket 
 // const bucketName = 'your-unique-bucket-name'; 
 // Imports the Google Cloud client library 
 const 
  
 { 
 Storage 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/storage 
' 
 ); 
 // Creates a client 
 const 
  
 storage 
  
 = 
  
 new 
  
 Storage 
 (); 
 async 
  
 function 
  
 getRetentionPolicy 
 () 
  
 { 
  
 const 
  
 [ 
 metadata 
 ] 
  
 = 
  
 await 
  
 storage 
 . 
 bucket 
 ( 
 bucketName 
 ). 
 getMetadata 
 (); 
  
 if 
  
 ( 
 metadata 
 . 
  retentionPolicy 
 
 ) 
  
 { 
  
 const 
  
 retentionPolicy 
  
 = 
  
 metadata 
 . 
  retentionPolicy 
 
 ; 
  
 console 
 . 
 log 
 ( 
 'A retention policy exists!' 
 ); 
  
 console 
 . 
 log 
 ( 
 `Period: 
 ${ 
  retentionPolicy 
 
 . 
 retentionPeriod 
 } 
 ` 
 ); 
  
 console 
 . 
 log 
 ( 
 `Effective time: 
 ${ 
  retentionPolicy 
 
 . 
 effectiveTime 
 } 
 ` 
 ); 
  
 if 
  
 ( 
  retentionPolicy 
 
 . 
 isLocked 
 ) 
  
 { 
  
 console 
 . 
 log 
 ( 
 'Policy is locked' 
 ); 
  
 } 
  
 else 
  
 { 
  
 console 
 . 
 log 
 ( 
 'Policy is unlocked' 
 ); 
  
 } 
  
 } 
 } 
 getRetentionPolicy 
 (). 
 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 .

      use Google\Cloud\Storage\StorageClient; 
 /** 
 * Gets a bucket's retention policy. 
 * 
 * @param string $bucketName The name of your Cloud Storage bucket. 
 *        (e.g. 'my-bucket') 
 */ 
 function get_retention_policy(string $bucketName): void 
 { 
 $storage = new StorageClient(); 
 $bucket = $storage->bucket($bucketName); 
 $bucket->reload(); 
 printf('Retention Policy for ' . $bucketName . PHP_EOL); 
 printf('Retention Period: ' . $bucket->info()['retentionPolicy']['retentionPeriod'] . PHP_EOL); 
 if (array_key_exists('isLocked', $bucket->info()['retentionPolicy']) 
&& $bucket->info()['retentionPolicy']['isLocked']) { 
 printf('Retention Policy is locked' . PHP_EOL); 
 } 
 if ($bucket->info()['retentionPolicy']['effectiveTime']) { 
 printf('Effective Time: ' . $bucket->info()['retentionPolicy']['effectiveTime'] . PHP_EOL); 
 } 
 }

    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 .

      from 
  
 google.cloud 
  
 import 
  storage 
 
 def 
  
 get_retention_policy 
 ( 
 bucket_name 
 ): 
  
 """Gets the retention policy on a given bucket""" 
 # bucket_name = "my-bucket" 
 storage_client 
 = 
  storage 
 
 . 
  Client 
 
 () 
 bucket 
 = 
 storage_client 
 . 
  bucket 
 
 ( 
 bucket_name 
 ) 
 bucket 
 . 
 reload 
 () 
 print 
 ( 
 f 
 "Retention Policy for 
 { 
 bucket_name 
 } 
 " 
 ) 
 print 
 ( 
 f 
 "Retention Period: 
 { 
 bucket 
 . 
  retention_period 
 
 } 
 " 
 ) 
 if 
 bucket 
 . 
  retention_policy_locked 
 
 : 
 print 
 ( 
 "Retention Policy is locked" 
 ) 
 if 
 bucket 
 . 
  retention_policy_effective_time 
 
 : 
 print 
 ( 
 f 
 "Effective Time: 
 { 
 bucket 
 . 
  retention_policy_effective_time 
 
 } 
 " 
 )

    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 .

      def 
  
 get_retention_policy 
  
 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 
  
 "Retention policy:" 
  
 puts 
  
 "period: 
 #{ 
 bucket 
 . 
  retention_period 
 
 } 
 " 
  
 puts 
  
 "effective time: 
 #{ 
 bucket 
 . 
  retention_effective_at 
 
 } 
 " 
  
 puts 
  
 "policy locked: 
 #{ 
 bucket 
 . 
  retention_policy_locked? 
 
 } 
 " 
 end

    REST APIs

    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 Bucket request that includes the desired fields :

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

      Where BUCKET_NAME is the name of the relevant bucket. For example, my-bucket .

      If the bucket has a retention policy set on it, the response looks like the following example:

       { 
  
 "retentionPolicy" 
 : 
  
 { 
  
 "retentionPeriod" 
 : 
  
 " TIME_IN_SECONDS 
" 
 , 
  
 "effectiveTime" 
 : 
  
 " DATETIME 
" 
 , 
  
 "isLocked" 
 : 
  
 " BOOLEAN 
" 
  
 }, 
 }

    XML API

    The XML API cannot be used to view the retention policy on a bucket. Use one of the other Cloud Storage tools, such as the Google Cloud console, instead.

    What's next

    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: