Enable and use object retention configurations

Overview

This page describes how to use the Object Retention Lock feature, including enabling it for a bucket and setting retention configurations for objects within the bucket.

Required roles

To get the permissions that you need to enable the Object Retention Lock feature for a bucket and set retention configurations on objects, ask your administrator to grant you the Storage Admin (roles/storage.admin) IAM role on the bucket or the project that contains the bucket. This predefined role contains the permissions required to set and manage retention configurations. To see the exact permissions that are required, expand the Required 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 the Google 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 the Google Cloud console to perform the instructions on this page.
  • storage.objects.overrideUnlockedRetention
    • This permission is only required if you plan on locking or shortening an existing retention configuration.
  • storage.objects.setRetention
  • storage.objects.update

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

For information about granting roles on buckets, see Set and manage IAM policies on buckets. For information about granting roles on projects, see Manage access to projects.

Enable object retentions for a bucket

Use the following instructions to allow retention configurations for objects in a bucket. If you want to enable object retention configurations for an existing bucket, 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 the Choose how to protect object data step, select Retention (For compliance) followed by Enable object retention.

To enable object retention configurations for an existing bucket:

  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 for which you want to enable object retentions.

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

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

  4. In the Object retention section, click Object Retention Not Enabled.

  5. In the dialog that appears, click Confirm.

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

//! [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 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.


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


importcom.google.cloud.storage.Bucket ;
importcom.google.cloud.storage.BucketInfo ;
importcom.google.cloud.storage.Storage ;
importcom.google.cloud.storage.StorageOptions ;
publicclass CreateBucketWithObjectRetention{
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";
Storage storage=StorageOptions .newBuilder().setProjectId(projectId).build().getService ();
Bucket bucket=
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 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
// 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.html
conststorage=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 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;
/**
 * 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 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.

fromgoogle.cloudimport storage
defcreate_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 query parameter enableObjectRetention=true as part of the request.

XML API

Create a bucket as you normally would, and include the header x-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 Storage Buckets page.

    Go to Buckets

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

  3. Click the Protection tab.

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

Command line

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

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

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:

per_object_retention:
 mode: Enabled

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.

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

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

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

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

To view a bucket's object retention configuration, follow the instructions for displaying a bucket's metadata and look for the 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;
publicclass GetBucketMetadata{
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";
Storage storage=StorageOptions .newBuilder().setProjectId(projectId).build().getService ();
// Select all fields. Fields can be selected individually e.g. Storage.BucketField.NAME
Bucket bucket=
storage.get (bucketName,Storage.BucketGetOption.fields(Storage.BucketField.values()));
// Print bucket metadata
System.out.println("BucketName: "+bucket.getName());
System.out.println("DefaultEventBasedHold: "+bucket.getDefaultEventBasedHold ());
System.out.println("DefaultKmsKeyName: "+bucket.getDefaultKmsKeyName ());
System.out.println("Id: "+bucket.getGeneratedId());
System.out.println("IndexPage: "+bucket.getIndexPage ());
System.out.println("Location: "+bucket.getLocation());
System.out.println("LocationType: "+bucket.getLocationType ());
System.out.println("Metageneration: "+bucket.getMetageneration());
System.out.println("NotFoundPage: "+bucket.getNotFoundPage ());
System.out.println("RetentionEffectiveTime: "+bucket.getRetentionEffectiveTime ());
System.out.println("RetentionPeriod: "+bucket.getRetentionPeriod ());
System.out.println("RetentionPolicyIsLocked: "+bucket.retentionPolicyIsLocked ());
System.out.println("RequesterPays: "+bucket.requesterPays());
System.out.println("SelfLink: "+bucket.getSelfLink());
System.out.println("StorageClass: "+bucket.getStorageClass().name ());
System.out.println("TimeCreated: "+bucket.getCreateTime());
System.out.println("VersioningEnabled: "+bucket.versioningEnabled ());
System.out.println("ObjectRetention: "+bucket.getObjectRetention ());
if(bucket.getLabels()!=null){
System.out.println("\n\n\nLabels:");
for(Map.Entry<String,String>label:bucket.getLabels().entrySet()){
System.out.println(label.getKey()+"="+label.getValue());
}
}
if(bucket.getLifecycleRules()!=null){
System.out.println("\n\n\nLifecycle Rules:");
for(BucketInfo.LifecycleRulerule:bucket.getLifecycleRules()){
System.out.println(rule);
}
}
}
}

Node.js

For more information, see the Cloud Storage Node.js API reference documentation.

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

To view a bucket's object retention configuration, follow the instructions for displaying a bucket's metadata and look for the object retention field in the response.
// Imports the Google Cloud client library
const{Storage}=require('@google-cloud/storage');
// Creates a client
conststorage=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 Metadata
const[metadata]=awaitstorage.bucket(bucketName).getMetadata();
console.log(JSON .stringify(metadata,null,2));
}

PHP

For more information, see the Cloud Storage PHP API reference documentation.

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

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

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

To view a bucket's object retention configuration, follow the instructions for displaying a bucket's metadata and look for the object retention field in the response.

fromgoogle.cloudimport storage
defbucket_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 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 objectRetention field:

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

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

XML 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 XML API with a GET 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"

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

Set an object's retention configuration

In order to set a retention configuration for an object, the object must be stored in a bucket for which object retentions are enabled. To set a retention configuration for an object:

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 contains the object whose retention configuration you want to set or modify.

    The Bucket details page opens, with the Objects tab selected.

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

  4. Click the name of the object.

    The Object details page opens, which displays object metadata.

  5. In the Protection section, click the Edit icon () associated with From object retention configuration.

    The Edit retention pane opens.

  6. In the Object retention configuration section, click Enabled or Disabled.

    1. If the retention configuration is enabled, select a date and time for the configuration in the Retain until time section, and click Unlocked or Locked in the Retention mode section.
  7. Click Confirm.

Command line

Use the gcloud storage objects update command with the appropriate flags. To add or modify a retention configuration, use the following command. Note that you must additionally include the --override-unlocked-retention flag if you are modifying an existing configuration 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 relevant bucket. For example, my-bucket.

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

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

  • STATE is either Locked or Unlocked.

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 following command:

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

Where:

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

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

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.

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


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 enabled
stringobjectName="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 parameter
file.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 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 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 ;
publicclass SetObjectRetentionPolicy{
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";
Storage storage=StorageOptions .newBuilder().setProjectId(projectId).build().getService ();
BlobId blobId=BlobId .of(bucketName,objectName);
Blob blob=storage.get (blobId);
if(blob==null){
System.out.println("The object "+objectName+" was not found in "+bucketName);
return;
}
Blob updated=
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 parameter
blob.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 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';
// 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 library
const{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.html
conststorage=newStorage();
asyncfunctionsetObjectRetentionPolicy(){
// Get a reference to the bucket
constmyBucket=storage.bucket(bucketName);
// Create a reference to a file object
constfile=myBucket.file(destFileName);
// Save the file data
awaitfile.save (contents);
// Set the retention policy for the file
constretentionDate=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 parameter
constnewRetentionDate=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 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;
/**
 * 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 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.

fromgoogle.cloudimport storage
defset_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_date
 blob.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_date
 blob.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 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:

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

    Where:

    • STATE is either Locked or Unlocked.

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

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

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

    Where:

    • JSON_FILE_NAME is the path for the file that you created in Step 2.
    • BUCKET_NAME is the name of the relevant bucket. For example, my-bucket.
    • OBJECT_NAME is the URL-encoded name of the relevant object. For example, pets/kitten.png, URL-encoded as pets%2Fkitten.png.
    • BOOLEAN must be true if the request shortens, removes, or locks an existing retention configuration. Otherwise, the overrideUnlockedRetention parameter can be excluded from the request entirely.

XML API

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

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

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

    Where:

    • STATE is either GOVERNANCE or COMPLIANCE.

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

  3. Use cURL to call the XML API with a PUT 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 XML file that you created in Step 2.
    • BOOLEAN must be true if the request shortens, removes, or locks an existing retention configuration. Otherwise, the x-goog-bypass-governance-retention header can be excluded from the request entirely.
    • BUCKET_NAME is the name of the relevant bucket. For example, my-bucket.
    • OBJECT_NAME is the URL-encoded name of the relevant object. For example, pets/kitten.png, URL-encoded as pets%2Fkitten.png.

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 Storage Buckets page.

    Go to Buckets

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

    The Bucket details page opens, with the Objects tab selected.

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

  4. Click the name of the object.

    The Object details page opens, which displays object metadata. Information about any retention configuration the object has is shown in the Protection section.

Command line

Use the gcloud 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 relevant bucket. For example, my-bucket.

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

If successful and a retention configuration exists for the object, the response 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 the object, the response is similar to the following:

null

Client libraries

C++

For more information, see the Cloud Storage C++ API reference documentation.

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

To view an object's retention configuration, follow the instructions for displaying a object's metadata and look for the 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 the Cloud Storage C# API reference documentation.

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

To view an object's retention configuration, follow the instructions for displaying a object's metadata and look for the 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 the Cloud Storage Java API reference documentation.

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

To view an object's retention configuration, follow the instructions for displaying a object's metadata and look for the 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;
publicclass GetObjectMetadata{
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";
Storage storage=StorageOptions .newBuilder().setProjectId(projectId).build().getService ();
// Select all fields
// Fields can be selected individually e.g. Storage.BlobField.CACHE_CONTROL
Blob blob=
storage.get (bucketName,blobName,Storage.BlobGetOption.fields(Storage.BlobField.values()));
// Print blob metadata
System.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 the Cloud Storage Node.js API reference documentation.

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

To view an object's retention configuration, follow the instructions for displaying a object's metadata and look for the 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 library
const{Storage}=require('@google-cloud/storage');
// Creates a client
conststorage=newStorage();
asyncfunctiongetMetadata(){
// Gets the metadata for the file
const[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 the Cloud Storage PHP API reference documentation.

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

To view an object's retention configuration, follow the instructions for displaying a object's metadata and look for the 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 the Cloud Storage Python API reference documentation.

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

To view an object's retention configuration, follow the instructions for displaying a object's metadata and look for the retention field in the response.
fromgoogle.cloudimport storage
defblob_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" if blob.temporary_hold else "disabled")
 print(
 "Event based hold: ",
 "enabled" if blob.event_based_hold else "disabled",
 )
 print(f"Retention mode: {blob.retention .mode }")
 print(f"Retention retain until time: {blob.retention .retain_until_time }")
 if blob.retention_expiration_time:
 print(
 f"retentionExpirationTime: {blob.retention_expiration_time}"
 )

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 Object request that includes the retention 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 relevant bucket. For example, my-bucket.
    • OBJECT_NAME is the name of the relevant object. For example, kitten.png.

XML 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 XML API with a GET 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 relevant bucket. For example, my-bucket.
    • OBJECT_NAME is the name of the relevant object. For example, kitten.png.

What's next

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

Last updated 2025年11月24日 UTC.