This page describes how to use object holds, including placing holds by default on new objects and placing holds on individual objects.
Prerequisites
Before using this feature in Cloud Storage, you should:
Have sufficient permission to view and update buckets and objects in Cloud Storage:
If you own the project that contains the bucket, you most likely have the necessary permissions.
If you use IAM, you should have
storage.buckets.update
,storage.buckets.get
,storage.objects.update
, andstorage.objects.get
permissions on the relevant bucket. See Using IAM Permissions for instructions on how to get a role, such as Storage Admin, that has these permissions.If you use ACLs, you should have OWNER permission on the relevant bucket and on the objects within it. See Setting ACLs for instructions on how to do this.
Working with the default event-based hold property
The following tasks show you how to enable, view, and disable the default event-based hold property on a bucket. When this property is enabled, new objects added to the bucket automatically get an event-based hold placed on them.
Enabling the default event-based hold property
To automatically place an event-based hold on each new object added to a bucket:
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser In the list of buckets, click on the name of the bucket that you want to enable the default event-based hold property for.
Select the Retention tab near the top of the page.
In the Default event-based hold option section, click the Disabled button.
If successful, the button changes to read Enabled.
See Troubleshooting for how to get detailed error information about failed operations in the Cloud Storage browser.
gsutil
Use the gsutil retention event-default set
command:
gsutil retention event-default set gs://BUCKET_NAME
Where BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create a .json file that contains the following information:
{ "defaultEventBasedHold": true }
Use
cURL
to call the JSON API with aPATCH
Bucket request:curl -X PATCH --data-binary @JSON_FILE_NAME.json \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=defaultEventBasedHold"
Where:
JSON_FILE_NAME
is the name of the file you created in Step 2.OAUTH2_TOKEN
is the access token you generated in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
XML API
The XML API cannot be used to work with object holds. Use one of the other Cloud Storage tools, such as gsutil, instead.
Getting the default hold status of a bucket
To view whether a bucket places event-based holds on new objects by default:
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser In the list of buckets, click on the name of the bucket that you want to check the default event-based status for.
Select the Retention tab near the top of the page.
The status appears in the Default event-based hold option section.
See Troubleshooting for how to get detailed error information about failed operations in the Cloud Storage browser.
gsutil
Use the following gsutil ls
command:
gsutil ls -L -b gs://BUCKET_NAME
Where BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
The response looks like the following example:
gs://my-bucket/ : Storage class: STANDARD ... ... Default Event-Based Hold: True ...
If the bucket does not place event-based holds on new objects by default,
gsutil omits Default Event-Based Hold
from the output entirely.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the JSON API with aGET
Bucket request that includes the desiredfields
:curl -X GET -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=defaultEventBasedHold"
Where
OAUTH2_TOKEN
is the access token you generated in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
If the bucket has a default event-based hold enabled for it, the response looks like the following example:
{ "retentionPolicy": true }
XML API
The XML API cannot be used to work with object holds. Use one of the other Cloud Storage tools, such as gsutil, instead.
Disabling a default event-based hold
To disable a default event-based hold on a bucket:
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser In the list of buckets, click on the name of the bucket that you want to disable the default event-based hold for.
Select the Retention tab near the top of the page.
In the Default event-based hold option section, click the Enabled button.
If successful, the button changes to read Disabled.
See Troubleshooting for how to get detailed error information about failed operations in the Cloud Storage browser.
gsutil
Use the gsutil retention event-default release
command:
gsutil retention event-default release gs://BUCKET_NAME
Where BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create a .json file that contains the following information:
{ "defaultEventBasedHold": false }
Use
cURL
to call the JSON API with aPATCH
Bucket request:curl -X PATCH --data-binary @JSON_FILE_NAME.json \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=defaultEventBasedHold"
Where:
JSON_FILE_NAME
is the name of the file you created in Step 2.OAUTH2_TOKEN
is the access token you generated in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
XML API
The XML API cannot be used to work with object holds. Use one of the other Cloud Storage tools, such as gsutil, instead.
Working with object holds
The following tasks show you how to place, view, and release holds on objects.
Placing an object hold
To place a hold on an object in your bucket:
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser In the list of buckets, click on the name of the bucket that has the objects you want to place holds on.
Select the checkbox next to the names of objects you want to place holds on.
Click the Manage holds button.
The Manage holds window appears.
Select the checkbox for the types of hold you want to place on the selected objects
Click Save hold settings.
See Troubleshooting for how to get detailed error information about failed operations in the Cloud Storage browser.
gsutil
Use the gsutil retention
command:
gsutil retention HOLD_TYPE set gs://BUCKET_NAME/OBJECT_NAME
Where:
HOLD_TYPE
is the type of hold you want to apply to your object. For example,temp
orevent
. See Object holds for more information about hold types.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.OBJECT_NAME
is the name of the relevant object. For example,pets/dog.png
.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
The following sample sets an event-based hold on an object: The following sample sets a temporary hold on an object:
For more information, see the
Cloud Storage C# API reference documentation.
The following sample sets an event-based hold on an object: The following sample sets a temporary hold on an object:
For more information, see the
Cloud Storage Go API reference documentation.
The following sample sets an event-based hold on an object: The following sample sets a temporary hold on an object:
For more information, see the
Cloud Storage Java API reference documentation.
The following sample sets an event-based hold on an object: The following sample sets a temporary hold on an object:
For more information, see the
Cloud Storage Node.js API reference documentation.
The following sample sets an event-based hold on an object: The following sample sets a temporary hold on an object:
For more information, see the
Cloud Storage PHP API reference documentation.
The following sample sets an event-based hold on an object: The following sample sets a temporary hold on an object:
For more information, see the
Cloud Storage Python API reference documentation.
The following sample sets an event-based hold on an object: The following sample sets a temporary hold on an object:
For more information, see the
Cloud Storage Ruby API reference documentation.
The following sample sets an event-based hold on an object: The following sample sets a temporary hold on an object:C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create a .json file that contains the following information:
{ "HOLD_TYPE": true }
Where
HOLD_TYPE
is the type of hold you want to apply to your object. For example,temporaryHold
oreventBasedHold
. See Object holds for more information about hold types.Use
cURL
to call the JSON API with aPATCH
Object request:curl -X PATCH --data-binary @JSON_FILE_NAME.json \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"
Where:
JSON_FILE_NAME
is the name of the file you created in Step 2.OAUTH2_TOKEN
is the access token you generated in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.OBJECT_NAME
is the name of the relevant object. For example,pets/dog.png
.
XML API
The XML API cannot be used to work with object holds. Use one of the other Cloud Storage tools, such as gsutil, instead.
Getting the hold status for an object
To view what, if any, holds exist on an object, follow the general instructions for Viewing Object Metadata.
Releasing an object hold
To release a hold on an object in your bucket:
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser In the list of buckets, click on the name of the bucket that has the objects you remove holds from.
Select the checkbox next to the names of objects you want to remove holds from.
Click the Manage holds button.
The Manage holds window appears.
De-select the checkbox for the holds you want to remove.
Click Save hold settings.
See Troubleshooting for how to get detailed error information about failed operations in the Cloud Storage browser.
gsutil
Use the gsutil retention
command:
gsutil retention HOLD_TYPE release gs://BUCKET_NAME/OBJECT_NAME
Where:
HOLD_TYPE
is the type of hold you want to release from your object. For example,temp
orevent
. See Object holds for more information about hold types.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.OBJECT_NAME
is the name of the relevant object. For example,pets/dog.png
.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
The following sample sets an event-based hold on an object: The following sample sets a temporary hold on an object:
For more information, see the
Cloud Storage C# API reference documentation.
The following sample releases an event-based hold on an object: The following sample releases a temporary hold on an object:
For more information, see the
Cloud Storage Go API reference documentation.
The following sample releases an event-based hold on an object: The following sample releases a temporary hold on an object:
For more information, see the
Cloud Storage Java API reference documentation.
The following sample releases an event-based hold on an object: The following sample releases a temporary hold on an object:
For more information, see the
Cloud Storage Node.js API reference documentation.
The following sample releases an event-based hold on an object: The following sample releases a temporary hold on an object:
For more information, see the
Cloud Storage PHP API reference documentation.
The following sample releases an event-based hold on an object: The following sample releases a temporary hold on an object:
For more information, see the
Cloud Storage Python API reference documentation.
The following sample releases an event-based hold on an object: The following sample releases a temporary hold on an object:
For more information, see the
Cloud Storage Ruby API reference documentation.
The following sample releases an event-based hold on an object: The following sample releases a temporary hold on an object:C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create a .json file that contains the following information:
{ "HOLD_TYPE": false }
Where
HOLD_TYPE
is the type of hold you want to release from your object. For example,temporaryHold
oreventBasedHold
. See Object holds for more information about hold types.Use
cURL
to call the JSON API with aPATCH
Object request:curl -X PATCH --data-binary @JSON_FILE_NAME.json \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"
Where:
JSON_FILE_NAME
is the name of the file you created in Step 2.OAUTH2_TOKEN
is the access token you generated in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.OBJECT_NAME
is the name of the relevant object. For example,pets/dog.png
.
XML API
The XML API cannot be used to work with object holds. Use one of the other Cloud Storage tools, such as gsutil, instead.
What's next
- Learn more about object holds, including the different types of holds that an object can have.
- Learn how to use retention policies.