This page describes how to use object holds, including placing holds by default on new objects and placing holds on individual objects.
Required permissions
Before using this feature in Cloud Storage, you must 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.
Use the default event-based hold property
The following tasks show you how to set and view 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.
Set the default event-based hold property
To enable or disable the default event-based hold property for a bucket:
Console
- In the Google Cloud console, go to the Cloud Storage Buckets page.
In the list of buckets, click on the name of the bucket that you want to set the default event-based hold property for.
Select the Protection tab near the top of the page.
The current status for the bucket appears in the Default event-based hold option section.
In the Default event-based hold option section, click the current status to change it.
The status appears as either Enabled or Disabled.
To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, see Troubleshooting.
Command line
gcloud
Use the gcloud storage buckets update
command with the
appropriate flag:
gcloud storage buckets update gs://BUCKET_NAME FLAG
Where:
BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.FLAG
is either--default-event-based-hold
to enable default event-based object holds or--no-default-event-based-hold
to disable them.
gsutil
Use the gsutil retention event-default
command:
gsutil retention event-default STATE gs://BUCKET_NAME
Where:
STATE
is eitherset
to use default event-based holds orrelease
to not use default event-based holds.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
Client libraries
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 a local development environment.
The following sample enables default event-based holds on a bucket: The following sample disables default event-based holds on a bucket:
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 a local development environment.
The following sample enables default event-based holds on a bucket: The following sample disables default event-based holds on a bucket:
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample enables default event-based holds on a bucket: The following sample disables default event-based holds on a bucket:
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 a local development environment.
The following sample enables default event-based holds on a bucket: The following sample disables default event-based holds on a bucket:
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 a local development environment.
The following sample enables default event-based holds on a bucket: The following sample disables default event-based holds on a bucket:
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 a local development environment.
The following sample enables default event-based holds on a bucket: The following sample disables default event-based holds on a bucket:
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 a local development environment.
The following sample enables default event-based holds on a bucket: The following sample disables default event-based holds on a bucket:
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample enables default event-based holds on a bucket: The following sample disables default event-based holds on a bucket: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. For instructions, see API authentication.
Create a JSON file that contains the following information:
{ "defaultEventBasedHold": STATE }
Where STATE is either
true
orfalse
.Use
cURL
to call the JSON API with aPATCH
Bucket request:curl -X PATCH --data-binary @JSON_FILE_NAME \ -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 path for the file that 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 the gcloud CLI, instead.
Get the default hold status of a bucket
To view whether a bucket places event-based holds on new objects by default:
Console
- In the Google Cloud console, go to the Cloud Storage Buckets page.
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 Protection tab near the top of the page.
The status appears in the Default event-based hold option section.
To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, see Troubleshooting.
Command line
gcloud
Use the gcloud storage buckets describe
command with the
--format
flag:
gcloud storage buckets describe gs://BUCKET_NAME --format="default(default_event_based_hold)"
Where BUCKET_NAME
is the name of the bucket
whose status you want to view. For example, my-bucket
.
If successful, the response looks similar to the following example:
default_event_based_hold: true
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.
Client libraries
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 a local development environment.
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 a local development environment.
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
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. For instructions, see API authentication.
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:
{ "defaultEventBasedHold": true }
XML API
The XML API cannot be used to work with object holds. Use one of the other Cloud Storage tools, such as the gcloud CLI, instead.
Manage individual object holds
The following tasks show you how to modify and view holds on individual objects.
Place or release an object hold
To place or release a hold on an object in your bucket:
Console
- In the Google Cloud console, go to the Cloud Storage Buckets page.
In the list of buckets, click on the name of the bucket that has the objects you want to place or remove holds on.
Select the checkbox next to the names of objects you want to place or remove holds on.
Click the Manage holds button.
The Manage holds window appears.
Toggle the checkboxes for each hold type as desired.
Click Save hold settings.
To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, see Troubleshooting.
Command line
gcloud
Use the gcloud storage objects update
command with the
appropriate flag::
gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME FLAG
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,pets/dog.png
.FLAG
is one of the following:--event-based-hold
to enable an event based hold on the object.--no-event-based-hold
to disable any event based hold on the object.--temporary-hold
to enable a temporary hold on the object.--no-temporary-hold
to disable any temporary hold on the object.
See Object holds for more information about hold types.
gsutil
Use the gsutil retention
command:
gsutil retention HOLD_TYPE STATE gs://BUCKET_NAME/OBJECT_NAME
Where:
HOLD_TYPE
is the type of hold you want to set or release on your object. For example,temp
orevent
. See Object holds for more information about hold types.STATE
is eitherset
to place the hold orrelease
to remove the hold.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
.
Client libraries
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 a local development environment.
The following sample sets an event-based hold on an object: The following sample releases an event-based hold on an object: The following sample sets a temporary hold on an object: The following sample releases a temporary hold on an object:
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 a local development environment.
The following sample sets an event-based hold on an object: The following sample releases an event-based hold on an object: The following sample sets a temporary 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.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample sets an event-based hold on an object: The following sample releases an event-based hold on an object: The following sample sets a temporary 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.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample sets an event-based hold on an object: The following sample releases an event-based hold on an object: The following sample sets a temporary 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.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample sets an event-based hold on an object: The following sample releases an event-based hold on an object: The following sample sets a temporary 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.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample sets an event-based hold on an object: The following sample releases an event-based hold on an object: The following sample sets a temporary 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.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample sets an event-based hold on an object: The following sample releases an event-based hold on an object: The following sample sets a temporary 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.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample sets an event-based hold on an object: The following sample releases an event-based hold on an object: The following sample sets a temporary 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. For instructions, see API authentication.
Create a JSON file that contains the following information:
{ "HOLD_TYPE": STATE }
Where:
HOLD_TYPE
is the type of hold you want to set or release on your object. For example,temporaryHold
oreventBasedHold
. See Object holds for more information about hold types.STATE
is eithertrue
to place the hold orfalse
to release the hold.
Use
cURL
to call the JSON API with aPATCH
Object request:curl -X PATCH --data-binary @JSON_FILE_NAME \ -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 path for the file that 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 URL-encoded name of the relevant object. For example,pets/dog.png
, URL-encoded aspets%2Fdog.png
.
XML API
The XML API cannot be used to work with object holds. Use one of the other Cloud Storage tools, such as the gcloud CLI, instead.
Get the hold status for an object
To view what, if any, holds exist on an object, follow the general instructions for viewing object metadata.
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.
- Learn how to use request preconditions to prevent race conditions.