Enable and use object retention configurations

Overview

This page describes how to use the Object Retention Lock feature, includingenabling it for a bucket and setting retention configurations for objectswithin the bucket.

Required roles

To get the permissions that you need to enable the Object Retention Lock featurefor a bucket and set retention configurations on objects, ask your administratorto grant you the Storage Admin (roles/storage.admin) IAM roleon the bucket or the project that contains the bucket. Thispredefined role contains the permissionsrequired to set and manage retention configurations. To see the exactpermissions that are required, expand theRequired permissions section:

Required permissions

  • storage.buckets.create
  • storage.buckets.enableObjectRetention
  • storage.buckets.get
  • storage.buckets.list
    • This permission is only required if you plan on using theGoogle Cloud console to perform the instructions on this page.
  • storage.objects.get
  • storage.objects.list
    • This permission is only required if you plan on using theGoogle Cloud console to perform the instructions on this page.
  • storage.objects.overrideUnlockedRetention
    • This permission is only required if you plan on locking or shorteningan existing retention configuration.
  • storage.objects.setRetention
  • storage.objects.update

You might also be able to get these permissions withcustom roles.

For information about granting roles on buckets, seeSet and manage IAM policies on buckets. For information about grantingroles on projects, seeManage access to projects.

Enable object retentions for a bucket

Important: Once the ability to set object retention configurations is enabledon a bucket, it cannot be disabled.

Use the following instructions to allow retention configurations for objects ina bucket. If you want to enable object retention configurations for an existingbucket, you must follow the Google Cloud console instructions.

Console

To enable object retention configurations for a new bucket:

  1. Create a bucket as you normally would, and in theChoose how toprotect object data step, selectRetention (For compliance)followed byEnable object retention.

To enable object retention configurations for an existing bucket:

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

  2. In the list of buckets, click the name of the bucket for which you wantto enable object retentions.

  3. Select theProtection tab near the top of the page.

    The bucket's object retention status is displayed in theObject retention section.

  4. In theObject retention section, clickObject Retention Not Enabled.

  5. In the dialog that appears, clickConfirm.

Command line

Create a bucket as you normally would, and include the--enable-per-object-retention flag in the command.

Client libraries

C++

For more information, see theCloud StorageC++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

//! [create-bucket-with-object-retention]namespacegcs=::google::cloud::storage;using::google::cloud::StatusOr;[](gcs::Clientclient,std::stringconst&bucket_name,std::stringconst&project_id){autobucket=client.CreateBucket(bucket_name,gcs::BucketMetadata{},gcs::EnableObjectRetention(true),gcs::OverrideDefaultProject(project_id));if(!bucket)throwstd::move(bucket).status();if(!bucket->has_object_retention()){throwstd::runtime_error("missing object retention in new bucket");}std::cout <<"Successfully created bucket " <<bucket_name            <<" with object retention: " <<bucket->object_retention()            <<"\n";}//! [create-bucket-with-object-retention]

C#

For more information, see theCloud StorageC# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

usingGoogle.Apis.Storage.v1.Data;usingGoogle.Cloud.Storage.V1;usingSystem;publicclassCreateBucketWithObjectRetentionSample{publicBucketCreateBucketWithObjectRetention(stringprojectId="your-project-id",stringbucketName="your-unique-bucket-name"){varstorage=StorageClient.Create();varbucket=storage.CreateBucket(projectId,bucketName,newCreateBucketOptions{ObjectRetentionEnabled=true});Console.WriteLine($"Created {bucketName}, with Object Retention enabled.");returnbucket;}}

Java

For more information, see theCloud StorageJava API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

importcom.google.cloud.storage.Bucket;importcom.google.cloud.storage.BucketInfo;importcom.google.cloud.storage.Storage;importcom.google.cloud.storage.StorageOptions;publicclassCreateBucketWithObjectRetention{publicstaticvoidcreateBucketWithObjectRetention(StringprojectId,StringbucketName){// The ID of your GCP project// String projectId = "your-project-id";// The ID to give your GCS bucket// String bucketName = "your-unique-bucket-name";Storagestorage=StorageOptions.newBuilder().setProjectId(projectId).build().getService();Bucketbucket=storage.create(BucketInfo.of(bucketName),Storage.BucketTargetOption.enableObjectRetention(true));System.out.println("Created bucket "+bucket.getName()+" with object retention enabled setting: "+bucket.getObjectRetention().getMode().toString());}}

Node.js

For more information, see theCloud StorageNode.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet 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 libraryconst{Storage}=require('@google-cloud/storage');// Creates a client// The bucket in the sample below will be created in the project associated with this client.// For more information, please see https://cloud.google.com/docs/authentication/production or https://googleapis.dev/nodejs/storage/latest/Storage.htmlconststorage=newStorage();asyncfunctioncreateBucketWithObjectRetention(){const[bucket]=awaitstorage.createBucket(bucketName,{enableObjectRetention:true,});console.log(`Created '${bucket.name}' with object retention enabled setting:${bucket.metadata.objectRetention.mode}`);}createBucketWithObjectRetention().catch(console.error);

PHP

For more information, see theCloud StoragePHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

use Google\Cloud\Storage\StorageClient;/** * Create a Cloud Storage bucket with the object retention enabled. * * @param string $bucketName The name of your Cloud Storage bucket. *        (e.g. 'my-bucket') */function create_bucket_with_object_retention(string $bucketName): void{    $storage = new StorageClient();    $bucket = $storage->createBucket($bucketName, [        'enableObjectRetention' => true    ]);    printf(        'Created bucket %s with object retention enabled setting: %s' . PHP_EOL,        $bucketName,        $bucket->info()['objectRetention']['mode']    );}

Python

For more information, see theCloud StoragePython API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

fromgoogle.cloudimportstoragedefcreate_bucket_object_retention(bucket_name):"""Creates a bucket with object retention enabled."""# The ID of your GCS bucket# bucket_name = "your-bucket-name"storage_client=storage.Client()bucket=storage_client.create_bucket(bucket_name,enable_object_retention=True)print(f"Created bucket{bucket_name} with object retention enabled setting:{bucket.object_retention_mode}")

REST APIs

JSON API

Create a bucket as you normally would, and include the queryparameterenableObjectRetention=true as part of the request.

XML API

Create a bucket as you normally would, and include the headerx-goog-bucket-object-lock-enabled: True as part of the request.

View a bucket's object retention status

To see if retention configurations can be set for objects in a bucket:

Console

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

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

  3. Click theProtection tab.

  4. The bucket's object retention status is displayed in theObject retention section.

Command line

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

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

WhereBUCKET_NAME is the name of the bucketwhose retention policy you want to view. For example,my-bucket.

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

per_object_retention:  mode: Enabled

If successful and a retention policy does not exist for the bucket, theresponse is similar to the following:

null

Client libraries

C++

For more information, see theCloud StorageC++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view a bucket's object retention configuration, follow the instructions for displaying a bucket's metadata and look forthe object retention field in the response.
namespacegcs=::google::cloud::storage;using::google::cloud::StatusOr;[](gcs::Clientclient,std::stringconst&bucket_name){StatusOr<gcs::BucketMetadata>bucket_metadata=client.GetBucketMetadata(bucket_name);if(!bucket_metadata)throwstd::move(bucket_metadata).status();std::cout <<"The metadata for bucket " <<bucket_metadata->name() <<" is "            <<*bucket_metadata <<"\n";}

C#

For more information, see theCloud StorageC# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view a bucket's object retention configuration, follow the instructions for displaying a bucket's metadata and look forthe object retention field in the response.
usingGoogle.Apis.Storage.v1.Data;usingGoogle.Cloud.Storage.V1;usingSystem;publicclassGetBucketMetadataSample{publicBucketGetBucketMetadata(stringbucketName="your-unique-bucket-name"){varstorage=StorageClient.Create();varbucket=storage.GetBucket(bucketName,newGetBucketOptions{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(varlabelinbucket.Labels){Console.WriteLine($"{label.Key}:\t{label.Value}");}}returnbucket;}}

Java

For more information, see theCloud StorageJava API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view a bucket's object retention configuration, follow the instructions for displaying a bucket's metadata and look forthe object retention field in the response.
importcom.google.cloud.storage.Bucket;importcom.google.cloud.storage.BucketInfo;importcom.google.cloud.storage.Storage;importcom.google.cloud.storage.StorageOptions;importjava.util.Map;publicclassGetBucketMetadata{publicstaticvoidgetBucketMetadata(StringprojectId,StringbucketName){// The ID of your GCP project// String projectId = "your-project-id";// The ID of your GCS bucket// String bucketName = "your-unique-bucket-name";Storagestorage=StorageOptions.newBuilder().setProjectId(projectId).build().getService();// Select all fields. Fields can be selected individually e.g. Storage.BucketField.NAMEBucketbucket=storage.get(bucketName,Storage.BucketGetOption.fields(Storage.BucketField.values()));// Print bucket metadataSystem.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.LifecycleRulerule:bucket.getLifecycleRules()){System.out.println(rule);}}}}

Node.js

For more information, see theCloud StorageNode.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view a bucket's object retention configuration, follow the instructions for displaying a bucket's metadata and look forthe object retention field in the response.
// Imports the Google Cloud client libraryconst{Storage}=require('@google-cloud/storage');// Creates a clientconststorage=newStorage();asyncfunctiongetBucketMetadata(){/**   * TODO(developer): Uncomment the following lines before running the sample.   */// The ID of your GCS bucket// const bucketName = 'your-unique-bucket-name';// Get Bucket Metadataconst[metadata]=awaitstorage.bucket(bucketName).getMetadata();console.log(JSON.stringify(metadata,null,2));}

PHP

For more information, see theCloud StoragePHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view a bucket's object retention configuration, follow the instructions for displaying a bucket's metadata and look forthe object retention 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 theCloud StoragePython API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view a bucket's object retention configuration, follow the instructions for displaying a bucket's metadata and look forthe object retention field in the response.
fromgoogle.cloudimportstoragedefbucket_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}")

REST APIs

JSON API

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. UsecURL to call the JSON API with aGET Bucket request that includes theobjectRetention field:

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

    WhereBUCKET_NAME is the name of therelevant bucket. For example,my-bucket.

XML API

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. UsecURL to call the XML API with aGET Bucket request scoped to?object-lock:

    curl -X GET \  -H "Authorization: Bearer $(gcloud auth print-access-token)" \  "https://storage.googleapis.com/BUCKET_NAME?object-lock"

    WhereBUCKET_NAME is the name of therelevant bucket. For example,my-bucket.

Set an object's retention configuration

Caution: Setting the mode of a retention configuration toLocked (COMPLIANCEin the XML API) is an irreversible action. If you do so:
  • You cannot remove the retention configuration from the object.
  • You cannot decrease the retention time for the object.

In order to set a retention configuration for an object, the object must bestored in a bucket for whichobject retentions are enabled. To set aretention configuration for an object:

Console

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

  2. In the list of buckets, click the name of the bucket that containsthe object whose retention configuration you want to set or modify.

    TheBucket details page opens, with theObjects tab selected.

  3. Navigate to the object, which might be located in a folder.

  4. Click the name of the object.

    TheObject details page opens, which displays object metadata.

  5. In theProtection section, click theEdit icon()associated withFrom object retention configuration.

    TheEdit retention pane opens.

  6. In theObject retention configuration section, clickEnabledorDisabled.

    1. If the retention configuration is enabled, select a date and timefor the configuration in theRetain until time section, andclickUnlocked orLocked in theRetention mode section.
  7. ClickConfirm.

Note: You can also set a retention configuration for an object at the timethe object is uploaded to the bucket. If the bucket you're uploading theobject to has the object retention feature enabled, a panel appears duringthe upload that lets you specify a retention configuration for the object.

Command line

Use thegcloud storage objects update command with theappropriate flags. To add or modify a retention configuration, use thefollowing command. Note that you must additionally include the--override-unlocked-retention flag if you are modifying an existingconfiguration in a way that locks it or shortens its retain-until time:

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME --retain-until=DATETIME --retention-mode=STATE

Where:

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

  • OBJECT_NAME is the name of the relevantobject. For example,kitten.png.

  • DATETIME is the earliest date and time thatthe object can be deleted. For example,2028-02-15T05:30:00Z.

  • STATE is eitherLocked orUnlocked.

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

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

To remove a retention configuration from an object, use the followingcommand:

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME --clear-retention --override-unlocked-retention

Where:

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

  • OBJECT_NAME is the name of the relevantobject. For example,kitten.png.

Note: You can also set a retention configuration for an object at thetime the object is written to the bucket. See command documentation,such asgcloud storage cp for more information.

Client libraries

C++

For more information, see theCloud StorageC++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

namespacegcs=::google::cloud::storage;using::google::cloud::StatusOr;[](gcs::Clientclient,std::stringconst&bucket_name,std::stringconst&object_name){autooriginal=client.GetObjectMetadata(bucket_name,object_name);if(!original)throwstd::move(original).status();autoconstuntil=std::chrono::system_clock::now()+std::chrono::hours(24);autoupdated=client.PatchObject(bucket_name,object_name,gcs::ObjectMetadataPatchBuilder().SetRetention(gcs::ObjectRetention{gcs::ObjectRetentionUnlocked(),until}),gcs::OverrideUnlockedRetention(true),gcs::IfMetagenerationMatch(original->metageneration()));if(!updated)throwstd::move(updated).status();std::cout <<"Successfully updated object retention configuration: "            <<*updated <<"\n";}

C#

For more information, see theCloud StorageC# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

usingGoogle.Cloud.Storage.V1;usingSystem;usingObject=Google.Apis.Storage.v1.Data.Object;publicclassSetObjectRetentionPolicySample{publicGoogle.Apis.Storage.v1.Data.ObjectSetObjectRetentionPolicy(stringbucketName="your-unique-bucket-name",// A bucket that has object retention enabledstringobjectName="your-object-name")// An object that does not have a retention policy set{varstorage=StorageClient.Create();varfile=storage.GetObject(bucketName,objectName);file.Retention=newObject.RetentionData{Mode="Unlocked",RetainUntilTimeDateTimeOffset=DateTimeOffset.UtcNow.AddDays(10)};file=storage.UpdateObject(file);Console.WriteLine($"The retention policy for object {objectName} was set to:");Console.WriteLine("Mode: "+file.Retention.Mode);Console.WriteLine("RetainUntilTime: "+file.Retention.RetainUntilTimeDateTimeOffset.ToString());// To modify an existing policy on an Unlocked object, pass in the override parameterfile.Retention=newObject.RetentionData{Mode="Unlocked",RetainUntilTimeDateTimeOffset=DateTimeOffset.UtcNow.AddDays(9)};file=storage.UpdateObject(file,newUpdateObjectOptions{OverrideUnlockedRetention=true});Console.WriteLine($"The retention policy for object {objectName} was updated to:");Console.WriteLine("Mode: "+file.Retention.Mode);Console.WriteLine("RetainUntilTime: "+file.Retention.RetainUntilTimeDateTimeOffset.ToString());returnfile;}}

Java

For more information, see theCloud StorageJava API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

import staticjava.time.OffsetDateTime.now;importcom.google.cloud.storage.Blob;importcom.google.cloud.storage.BlobId;importcom.google.cloud.storage.BlobInfo.Retention;importcom.google.cloud.storage.Storage;importcom.google.cloud.storage.StorageException;importcom.google.cloud.storage.StorageOptions;publicclassSetObjectRetentionPolicy{publicstaticvoidsetObjectRetentionPolicy(StringprojectId,StringbucketName,StringobjectName)throwsStorageException{// The ID of your GCP project// String projectId = "your-project-id";// The ID of your GCS bucket that has object retention enabled// String bucketName = "your-unique-bucket-name";// The ID of your GCS object// String objectName = "your-object-name";Storagestorage=StorageOptions.newBuilder().setProjectId(projectId).build().getService();BlobIdblobId=BlobId.of(bucketName,objectName);Blobblob=storage.get(blobId);if(blob==null){System.out.println("The object "+objectName+" was not found in "+bucketName);return;}Blobupdated=blob.toBuilder().setRetention(Retention.newBuilder().setMode(Retention.Mode.UNLOCKED).setRetainUntilTime(now().plusDays(10)).build()).build().update();System.out.println("Retention policy for object "+objectName+" was set to:");System.out.println(updated.getRetention().toString());// To modify an existing policy on an Unlocked object, pass in the override parameterblob.toBuilder().setRetention(updated.getRetention().toBuilder().setRetainUntilTime(now().plusDays(9)).build()).build().update(Storage.BlobTargetOption.overrideUnlockedRetention(true));System.out.println("Retention policy for object "+objectName+" was updated to:");System.out.println(storage.get(blobId).getRetention().toString());}}

Node.js

For more information, see theCloud StorageNode.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet 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';// The new ID for your GCS file// const destFileName = 'your-new-file-name';// The content to be uploaded in the GCS file// const contents = 'your file content';// Imports the Google Cloud client libraryconst{Storage}=require('@google-cloud/storage');// Creates a client// The bucket in the sample below will be created in the project associated with this client.// For more information, please see https://cloud.google.com/docs/authentication/production or https://googleapis.dev/nodejs/storage/latest/Storage.htmlconststorage=newStorage();asyncfunctionsetObjectRetentionPolicy(){// Get a reference to the bucketconstmyBucket=storage.bucket(bucketName);// Create a reference to a file objectconstfile=myBucket.file(destFileName);// Save the file dataawaitfile.save(contents);// Set the retention policy for the fileconstretentionDate=newDate();retentionDate.setDate(retentionDate.getDate()+10);const[metadata]=awaitfile.setMetadata({retention:{mode:'Unlocked',retainUntilTime:retentionDate.toISOString(),},});console.log(`Retention policy for file${file.name} was set to:${metadata.retention.mode}`);// To modify an existing policy on an unlocked file object, pass in the override parameterconstnewRetentionDate=newDate(retentionDate.getDate());newRetentionDate.setDate(newRetentionDate.getDate()+9);const[newMetadata]=awaitfile.setMetadata({retention:{mode:'Unlocked',retainUntilTime:newRetentionDate,},overrideUnlockedRetention:true,});console.log(`Retention policy for file${file.name} was updated to:${newMetadata.retention.retainUntilTime}`);}setObjectRetentionPolicy().catch(console.error);

PHP

For more information, see theCloud StoragePHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

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 string $objectName The name of your Cloud Storage object. *        (e.g. 'my-object') */function set_object_retention_policy(string $bucketName, string $objectName): void{    $storage = new StorageClient();    $bucket = $storage->bucket($bucketName);    $object = $bucket->object($objectName);    $expires = (new \DateTime)->add(        \DateInterval::createFromDateString('+10 days')    );    // To modify an existing policy on an Unlocked object, pass the override parameter    $object->update([        'retention' => [            'mode' => 'Unlocked',            'retainUntilTime' => $expires->format(\DateTime::RFC3339)        ],        'overrideUnlockedRetention' => true    ]);    printf(        'Retention policy for object %s was updated to: %s' . PHP_EOL,        $objectName,        $object->info()['retention']['retainUntilTime']    );}

Python

For more information, see theCloud StoragePython API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

fromgoogle.cloudimportstoragedefset_object_retention_policy(bucket_name,contents,destination_blob_name):"""Set the object retention policy of a file."""# The ID of your GCS bucket# bucket_name = "your-bucket-name"# The contents to upload to the file# contents = "these are my contents"# The ID of your GCS object# destination_blob_name = "storage-object-name"storage_client=storage.Client()bucket=storage_client.bucket(bucket_name)blob=bucket.blob(destination_blob_name)blob.upload_from_string(contents)# Set the retention policy for the file.blob.retention.mode="Unlocked"retention_date=datetime.datetime.now(datetime.timezone.utc)+datetime.timedelta(days=10)blob.retention.retain_until_time=retention_dateblob.patch()print(f"Retention policy for file{destination_blob_name} was set to:{blob.retention.mode}.")# To modify an existing policy on an unlocked file object, pass in the override parameter.new_retention_date=datetime.datetime.now(datetime.timezone.utc)+datetime.timedelta(days=9)blob.retention.retain_until_time=new_retention_dateblob.patch(override_unlocked_retention=True)print(f"Retention policy for file{destination_blob_name} was updated to:{blob.retention.retain_until_time}.")

REST APIs

JSON API

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. Create a JSON file that contains the following information:

    {"retention":{"mode":STATE,"retainUntilTime":"DATETIME"}}

    Where:

    • STATE is eitherLocked orUnlocked.

    • DATETIME is the earliest date and timethat the object can be deleted. For example,2028-02-15T05:30:00Z.

  3. UsecURL to call the JSON API with aPATCH Object request:

    curl -X PATCH --data-binary @JSON_FILE_NAME \-H "Authorization: Bearer $(gcloud auth print-access-token)" \-H "Content-Type: application/json" \"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?overrideUnlockedRetention=BOOLEAN"

    Where:

    • JSON_FILE_NAME is the path for the filethat you created in Step 2.
    • BUCKET_NAME is the name of the relevantbucket. For example,my-bucket.
    • OBJECT_NAME is the URL-encoded name of therelevant object. For example,pets/kitten.png, URL-encoded aspets%2Fkitten.png.
    • BOOLEAN must betrue if the requestshortens, removes, or locks an existing retention configuration.Otherwise, theoverrideUnlockedRetention parameter can beexcluded from the request entirely.
Note: You can also set a retention configuration for an object at thetime the object is written to the bucket. See request documentation,such asObjects: Insert for more information.

XML API

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. Create an XML file that contains the following information:

    <Retention>  <Mode>STATE  </Mode>  <RetainUntilDate>DATETIME  </RetainUntilDate></Retention>

    Where:

    • STATE is eitherGOVERNANCE orCOMPLIANCE.

    • DATETIME is the earliest date and timethat the object can be deleted. For example,2028-02-15T05:30:00Z.

  3. UsecURL to call the XML API with aPUT Object request scoped to?retention:

    curl -X PUT --data-binary @XML_FILE_NAME \  -H "Authorization: Bearer $(gcloud auth print-access-token)" \  -H "x-goog-bypass-governance-retention:BOOLEAN" \  "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME?retention"

    Where:

    • XML_FILE_NAME is the path for the XMLfile that you created in Step 2.
    • BOOLEAN must betrue if the requestshortens, removes, or locks an existing retention configuration.Otherwise, thex-goog-bypass-governance-retention header can beexcluded from the request entirely.
    • BUCKET_NAME is the name of the relevantbucket. For example,my-bucket.
    • OBJECT_NAME is the URL-encoded name of therelevant object. For example,pets/kitten.png, URL-encoded aspets%2Fkitten.png.
Note: You can also set a retention configuration for an object at thetime the object is written to the bucket. See request documentation,such asPUT Object for more information.

View an object's retention configuration

To view what, if any, retention configuration is set on an object:

Console

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

  2. In the list of buckets, click the name of the bucket that containsthe object whose retention configuration you want to view.

    TheBucket details page opens, with theObjects tab selected.

  3. Navigate to the object, which might be located in a folder.

  4. Click the name of the object.

    TheObject details page opens, which displays object metadata.Information about any retention configuration the object has is shownin theProtection section.

Command line

Use thegcloud storage objects describe command with the--format flag:

gcloud storage objects describe gs://BUCKET_NAME/OBJECT_NAME --format="default(retention_settings)"

Where:

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

  • OBJECT_NAME is the name of the relevantobject. For example,kitten.png.

If successful and a retention configuration exists for the object, theresponse is similar to the following:

retention_settings:  mode: Unlocked  retainUntilTime: '2028-11-30T14:11:14+00:00'

If successful and a retention configuration does not exist for theobject, the response is similar to the following:

null

Client libraries

C++

For more information, see theCloud StorageC++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view an object's retention configuration, follow the instructions for displaying a object's metadata and look forthe retention field in the response.
namespacegcs=::google::cloud::storage;using::google::cloud::StatusOr;[](gcs::Clientclient,std::stringconst&bucket_name,std::stringconst&object_name){StatusOr<gcs::ObjectMetadata>object_metadata=client.GetObjectMetadata(bucket_name,object_name);if(!object_metadata)throwstd::move(object_metadata).status();std::cout <<"The metadata for object " <<object_metadata->name()            <<" in bucket " <<object_metadata->bucket() <<" is "            <<*object_metadata <<"\n";}

C#

For more information, see theCloud StorageC# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view an object's retention configuration, follow the instructions for displaying a object's metadata and look forthe retention field in the response.
usingGoogle.Cloud.Storage.V1;usingSystem;publicclassGetMetadataSample{publicGoogle.Apis.Storage.v1.Data.ObjectGetMetadata(stringbucketName="your-unique-bucket-name",stringobjectName="your-object-name"){varstorage=StorageClient.Create();varstorageObject=storage.GetObject(bucketName,objectName,newGetObjectOptions{Projection=Projection.Full});Console.WriteLine($"Bucket:\t{storageObject.Bucket}");Console.WriteLine($"CacheControl:\t{storageObject.CacheControl}");Console.WriteLine($"ComponentCount:\t{storageObject.ComponentCount}");Console.WriteLine($"ContentDisposition:\t{storageObject.ContentDisposition}");Console.WriteLine($"ContentEncoding:\t{storageObject.ContentEncoding}");Console.WriteLine($"ContentLanguage:\t{storageObject.ContentLanguage}");Console.WriteLine($"ContentType:\t{storageObject.ContentType}");Console.WriteLine($"Crc32c:\t{storageObject.Crc32c}");Console.WriteLine($"ETag:\t{storageObject.ETag}");Console.WriteLine($"Generation:\t{storageObject.Generation}");Console.WriteLine($"Id:\t{storageObject.Id}");Console.WriteLine($"Kind:\t{storageObject.Kind}");Console.WriteLine($"KmsKeyName:\t{storageObject.KmsKeyName}");Console.WriteLine($"Md5Hash:\t{storageObject.Md5Hash}");Console.WriteLine($"MediaLink:\t{storageObject.MediaLink}");Console.WriteLine($"Metageneration:\t{storageObject.Metageneration}");Console.WriteLine($"Name:\t{storageObject.Name}");Console.WriteLine($"Retention:\t{storageObject.Retention}");Console.WriteLine($"Size:\t{storageObject.Size}");Console.WriteLine($"StorageClass:\t{storageObject.StorageClass}");Console.WriteLine($"TimeCreated:\t{storageObject.TimeCreated}");Console.WriteLine($"Updated:\t{storageObject.Updated}");booleventBasedHold=storageObject.EventBasedHold??false;Console.WriteLine("Event-based hold enabled? {0}",eventBasedHold);booltemporaryHold=storageObject.TemporaryHold??false;Console.WriteLine("Temporary hold enabled? {0}",temporaryHold);Console.WriteLine($"RetentionExpirationTime\t{storageObject.RetentionExpirationTime}");if(storageObject.Metadata!=null){Console.WriteLine("Metadata: ");foreach(varmetadatainstorageObject.Metadata){Console.WriteLine($"{metadata.Key}:\t{metadata.Value}");}}Console.WriteLine($"CustomTime:\t{storageObject.CustomTime}");returnstorageObject;}}

Java

For more information, see theCloud StorageJava API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view an object's retention configuration, follow the instructions for displaying a object's metadata and look forthe retention field in the response.
importcom.google.cloud.storage.Blob;importcom.google.cloud.storage.Storage;importcom.google.cloud.storage.StorageException;importcom.google.cloud.storage.StorageOptions;importjava.util.Date;importjava.util.Map;publicclassGetObjectMetadata{publicstaticvoidgetObjectMetadata(StringprojectId,StringbucketName,StringblobName)throwsStorageException{// The ID of your GCP project// String projectId = "your-project-id";// The ID of your GCS bucket// String bucketName = "your-unique-bucket-name";// The ID of your GCS object// String objectName = "your-object-name";Storagestorage=StorageOptions.newBuilder().setProjectId(projectId).build().getService();// Select all fields// Fields can be selected individually e.g. Storage.BlobField.CACHE_CONTROLBlobblob=storage.get(bucketName,blobName,Storage.BlobGetOption.fields(Storage.BlobField.values()));// Print blob metadataSystem.out.println("Bucket: "+blob.getBucket());System.out.println("CacheControl: "+blob.getCacheControl());System.out.println("ComponentCount: "+blob.getComponentCount());System.out.println("ContentDisposition: "+blob.getContentDisposition());System.out.println("ContentEncoding: "+blob.getContentEncoding());System.out.println("ContentLanguage: "+blob.getContentLanguage());System.out.println("ContentType: "+blob.getContentType());System.out.println("CustomTime: "+blob.getCustomTime());System.out.println("Crc32c: "+blob.getCrc32c());System.out.println("Crc32cHexString: "+blob.getCrc32cToHexString());System.out.println("ETag: "+blob.getEtag());System.out.println("Generation: "+blob.getGeneration());System.out.println("Id: "+blob.getBlobId());System.out.println("KmsKeyName: "+blob.getKmsKeyName());System.out.println("Md5Hash: "+blob.getMd5());System.out.println("Md5HexString: "+blob.getMd5ToHexString());System.out.println("MediaLink: "+blob.getMediaLink());System.out.println("Metageneration: "+blob.getMetageneration());System.out.println("Name: "+blob.getName());System.out.println("Size: "+blob.getSize());System.out.println("StorageClass: "+blob.getStorageClass());System.out.println("TimeCreated: "+newDate(blob.getCreateTime()));System.out.println("Last Metadata Update: "+newDate(blob.getUpdateTime()));System.out.println("Object Retention Policy: "+blob.getRetention());BooleantemporaryHoldIsEnabled=(blob.getTemporaryHold()!=null &&blob.getTemporaryHold());System.out.println("temporaryHold: "+(temporaryHoldIsEnabled?"enabled":"disabled"));BooleaneventBasedHoldIsEnabled=(blob.getEventBasedHold()!=null &&blob.getEventBasedHold());System.out.println("eventBasedHold: "+(eventBasedHoldIsEnabled?"enabled":"disabled"));if(blob.getRetentionExpirationTime()!=null){System.out.println("retentionExpirationTime: "+newDate(blob.getRetentionExpirationTime()));}if(blob.getMetadata()!=null){System.out.println("\n\n\nUser metadata:");for(Map.Entry<String,String>userMetadata:blob.getMetadata().entrySet()){System.out.println(userMetadata.getKey()+"="+userMetadata.getValue());}}}}

Node.js

For more information, see theCloud StorageNode.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view an object's retention configuration, follow the instructions for displaying a object's metadata and look forthe retention field in the response.
/** * TODO(developer): Uncomment the following lines before running the sample. */// The ID of your GCS bucket// const bucketName = 'your-unique-bucket-name';// The ID of your GCS file// const fileName = 'your-file-name';// Imports the Google Cloud client libraryconst{Storage}=require('@google-cloud/storage');// Creates a clientconststorage=newStorage();asyncfunctiongetMetadata(){// Gets the metadata for the fileconst[metadata]=awaitstorage.bucket(bucketName).file(fileName).getMetadata();console.log(`Bucket:${metadata.bucket}`);console.log(`CacheControl:${metadata.cacheControl}`);console.log(`ComponentCount:${metadata.componentCount}`);console.log(`ContentDisposition:${metadata.contentDisposition}`);console.log(`ContentEncoding:${metadata.contentEncoding}`);console.log(`ContentLanguage:${metadata.contentLanguage}`);console.log(`ContentType:${metadata.contentType}`);console.log(`CustomTime:${metadata.customTime}`);console.log(`Crc32c:${metadata.crc32c}`);console.log(`ETag:${metadata.etag}`);console.log(`Generation:${metadata.generation}`);console.log(`Id:${metadata.id}`);console.log(`KmsKeyName:${metadata.kmsKeyName}`);console.log(`Md5Hash:${metadata.md5Hash}`);console.log(`MediaLink:${metadata.mediaLink}`);console.log(`Metageneration:${metadata.metageneration}`);console.log(`Name:${metadata.name}`);console.log(`Size:${metadata.size}`);console.log(`StorageClass:${metadata.storageClass}`);console.log(`TimeCreated:${newDate(metadata.timeCreated)}`);console.log(`Last Metadata Update:${newDate(metadata.updated)}`);console.log(`TurboReplication:${metadata.rpo}`);console.log(`temporaryHold:${metadata.temporaryHold?'enabled':'disabled'}`);console.log(`eventBasedHold:${metadata.eventBasedHold?'enabled':'disabled'}`);if(metadata.retentionExpirationTime){console.log(`retentionExpirationTime:${newDate(metadata.retentionExpirationTime)}`);}if(metadata.metadata){console.log('\n\n\nUser metadata:');for(constkeyinmetadata.metadata){console.log(`${key}=${metadata.metadata[key]}`);}}}getMetadata().catch(console.error);

PHP

For more information, see theCloud StoragePHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view an object's retention configuration, follow the instructions for displaying a object's metadata and look forthe retention field in the response.
use Google\Cloud\Storage\StorageClient;/** * List object metadata. * * @param string $bucketName The name of your Cloud Storage bucket. *        (e.g. 'my-bucket') * @param string $objectName The name of your Cloud Storage object. *        (e.g. 'my-object') */function object_metadata(string $bucketName, string $objectName): void{    $storage = new StorageClient();    $bucket = $storage->bucket($bucketName);    $object = $bucket->object($objectName);    $info = $object->info();    if (isset($info['name'])) {        printf('Blob: %s' . PHP_EOL, $info['name']);    }    if (isset($info['bucket'])) {        printf('Bucket: %s' . PHP_EOL, $info['bucket']);    }    if (isset($info['storageClass'])) {        printf('Storage class: %s' . PHP_EOL, $info['storageClass']);    }    if (isset($info['id'])) {        printf('ID: %s' . PHP_EOL, $info['id']);    }    if (isset($info['size'])) {        printf('Size: %s' . PHP_EOL, $info['size']);    }    if (isset($info['updated'])) {        printf('Updated: %s' . PHP_EOL, $info['updated']);    }    if (isset($info['generation'])) {        printf('Generation: %s' . PHP_EOL, $info['generation']);    }    if (isset($info['metageneration'])) {        printf('Metageneration: %s' . PHP_EOL, $info['metageneration']);    }    if (isset($info['etag'])) {        printf('Etag: %s' . PHP_EOL, $info['etag']);    }    if (isset($info['crc32c'])) {        printf('Crc32c: %s' . PHP_EOL, $info['crc32c']);    }    if (isset($info['md5Hash'])) {        printf('MD5 Hash: %s' . PHP_EOL, $info['md5Hash']);    }    if (isset($info['contentType'])) {        printf('Content-type: %s' . PHP_EOL, $info['contentType']);    }    if (isset($info['temporaryHold'])) {        printf('Temporary hold: %s' . PHP_EOL, ($info['temporaryHold'] ? 'enabled' : 'disabled'));    }    if (isset($info['eventBasedHold'])) {        printf('Event-based hold: %s' . PHP_EOL, ($info['eventBasedHold'] ? 'enabled' : 'disabled'));    }    if (isset($info['retentionExpirationTime'])) {        printf('Retention Expiration Time: %s' . PHP_EOL, $info['retentionExpirationTime']);    }    if (isset($info['retention'])) {        printf('Retention mode: %s' . PHP_EOL, $info['retention']['mode']);        printf('Retain until time is: %s' . PHP_EOL, $info['retention']['retainUntilTime']);    }    if (isset($info['customTime'])) {        printf('Custom Time: %s' . PHP_EOL, $info['customTime']);    }    if (isset($info['metadata'])) {        printf('Metadata: %s' . PHP_EOL, print_r($info['metadata'], true));    }}

Python

For more information, see theCloud StoragePython API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view an object's retention configuration, follow the instructions for displaying a object's metadata and look forthe retention field in the response.
fromgoogle.cloudimportstoragedefblob_metadata(bucket_name,blob_name):"""Prints out a blob's metadata."""# bucket_name = 'your-bucket-name'# blob_name = 'your-object-name'storage_client=storage.Client()bucket=storage_client.bucket(bucket_name)# Retrieve a blob, and its metadata, from Google Cloud Storage.# Note that `get_blob` differs from `Bucket.blob`, which does not# make an HTTP request.blob=bucket.get_blob(blob_name)print(f"Blob:{blob.name}")print(f"Bucket:{blob.bucket.name}")print(f"Storage class:{blob.storage_class}")print(f"ID:{blob.id}")print(f"Size:{blob.size} bytes")print(f"Updated:{blob.updated}")print(f"Generation:{blob.generation}")print(f"Metageneration:{blob.metageneration}")print(f"Etag:{blob.etag}")print(f"Owner:{blob.owner}")print(f"Component count:{blob.component_count}")print(f"Crc32c:{blob.crc32c}")print(f"md5_hash:{blob.md5_hash}")print(f"Cache-control:{blob.cache_control}")print(f"Content-type:{blob.content_type}")print(f"Content-disposition:{blob.content_disposition}")print(f"Content-encoding:{blob.content_encoding}")print(f"Content-language:{blob.content_language}")print(f"Metadata:{blob.metadata}")print(f"Medialink:{blob.media_link}")print(f"Custom Time:{blob.custom_time}")print("Temporary hold: ","enabled"ifblob.temporary_holdelse"disabled")print("Event based hold: ","enabled"ifblob.event_based_holdelse"disabled",)print(f"Retention mode:{blob.retention.mode}")print(f"Retention retain until time:{blob.retention.retain_until_time}")ifblob.retention_expiration_time:print(f"retentionExpirationTime:{blob.retention_expiration_time}")

REST APIs

JSON API

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. UsecURL to call the JSON API with aGET Object request that includes theretention field:

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

    Where:

    • BUCKET_NAME is the name of the relevantbucket. For example,my-bucket.
    • OBJECT_NAME is the name of the relevantobject. For example,kitten.png.

XML API

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. UsecURL to call the XML API with aGET Object request scoped to?retention:

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

    Where:

    • BUCKET_NAME is the name of the relevantbucket. For example,my-bucket.
    • OBJECT_NAME is the name of the relevantobject. For example,kitten.png.

What's next

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

Last updated 2025-12-15 UTC.