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 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
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.
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
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.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 $(gcloud auth print-access-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.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 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
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
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
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.Use
cURL
to call the JSON API with aGET
Bucket request that includes the desiredfields
:curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=defaultEventBasedHold"
Where
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 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
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.
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
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.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 $(gcloud auth print-access-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.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.