Use object holds (original) (raw)

Skip to main content

• Technology areas

  • Overview
  • Guides
  • Reference
  • Samples
  • Resources

• Cross-product tools

• Console

• Discover

• Product overview

• Storage Intelligence overview

• Get started

• Terraform support for Cloud Storage

• Configure and manage Storage Intelligence

• Create buckets

• Create a bucket

• Domain-named bucket verification

• Access and manage buckets

• List buckets

• Change the default storage class of a bucket

• Move and rename buckets

• Delete buckets

• Upload and download objects

• About objects

• Overview of uploads and downloads

• Access and manage objects

• List objects

• Copy, rename, and move objects

• Change an object's storage class

• Tools to access and manage objects using a directory structure

• Object transcoding

• Delete objects

• Get insights on your stored data

• Analyze stored data with Gemini Cloud Assist

• Cache objects

• About caching

• Control data lifecycles

• Options for controlling data lifecycles

• Make requests

• Consistency in Cloud Storage operations

• Batched requests

• Use long-running operations

• Paginate results

• URI wildcards

• Secure data

• Access control

  • Overview
  • Bucket IP filtering
    * Overview
    * Create a bucket with IP filtering rules
    * Create or update IP filtering rules on an existing bucket
    * Get IP bucket filtering rules
    * List bucket IP filtering rules
    * Delete bucket IP filtering rules
    * Disable bucket IP filtering
    * Bypass bucket IP filtering rules
  • Sharing and collaboration scenarios
  • Access control best practices

• Monitor data and usage

• Use Cloud Audit Logs with Cloud Storage

• Usage logs and storage logs

• Use Cloud Audit Logs with storage batch operations

• Use Cloud Logs with storage batch operations

• Use Cloud Audit Logs with Storage Insights

• Use gRPC client-side metrics

• Use client-side traces

• Protection, backup, and recovery

• Overview

• Soft delete

  • Overview
  • Set and manage soft delete policies
  • Use soft-deleted objects
  • Use soft-deleted buckets
  • Set a default soft delete retention duration
  • Use soft delete recommendations
  • Disable soft delete

• Mount buckets with Cloud Storage FUSE

• Overview

• Quickstart

• Install Cloud Storage FUSE

• Mount buckets

• Performance

  • Performance tuning best practices
  • Profile-based configurations for AI/ML workloads
  • Automated configuration values for high-performance machine types
  • Use pre-configured GKE YAML files to optimize Cloud Storage FUSE performance

• Work across products, Clouds, and platforms

• Best practices for media workloads

• Interoperability

• Use Cloud Storage with Big Data

• Integration with Google Cloud Platform services and tools

• Troubleshoot

• Troubleshooting common issues

• Troubleshooting Storage Insights issues

• Troubleshooting Cloud Storage FUSE issues

Use object holds

Overview

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, and storage.objects.getpermissions 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 thedefault 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

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 you want to set the default event-based hold property for.
3. 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.
4. 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, seeTroubleshooting.

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

C++

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

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

The following sample enables default event-based holds on a bucket:

The following sample disables default event-based holds on a bucket:

C#

For more information, see theCloud Storage C# API reference documentation.

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

The following sample enables default event-based holds on a bucket:

The following sample disables default event-based holds on a bucket:

Go

For more information, see theCloud Storage Go API reference documentation.

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

The following sample enables default event-based holds on a bucket:

The following sample disables default event-based holds on a bucket:

Java

For more information, see theCloud Storage Java API reference documentation.

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

The following sample enables default event-based holds on a bucket:

The following sample disables default event-based holds on a bucket:

Node.js

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

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

The following sample enables default event-based holds on a bucket:

The following sample disables default event-based holds on a bucket:

PHP

For more information, see theCloud Storage PHP API reference documentation.

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

The following sample enables default event-based holds on a bucket:

The following sample disables default event-based holds on a bucket:

Python

For more information, see theCloud Storage Python API reference documentation.

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

The following sample enables default event-based holds on a bucket:

The following sample disables default event-based holds on a bucket:

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

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

The following sample enables default event-based holds on a bucket:

The following sample disables default event-based holds on a bucket:

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:
   {
   "defaultEventBasedHold": STATE
   }
   Where STATE is either true or false.
3. Use cURL to call the JSON API with a PATCH Bucketrequest:
   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

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 you want to check the default event-based status for.
3. Select the Protection tab near the top of the page.
4. 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, seeTroubleshooting.

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

C++

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

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

C#

For more information, see theCloud Storage C# API reference documentation.

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

Go

For more information, see theCloud Storage Go API reference documentation.

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

Java

For more information, see theCloud Storage Java API reference documentation.

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

Node.js

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

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

PHP

For more information, see theCloud Storage PHP API reference documentation.

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

Python

For more information, see theCloud Storage Python API reference documentation.

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

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

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

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 Bucketrequest that includes the desired fields:
   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

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 has the objects you want to place or remove holds on.
3. Select the checkbox next to the names of objects you want to place or remove holds on.
4. Click the Manage holds button.
   The Manage holds window appears.
5. Toggle the checkboxes for each hold type as desired.
6. Click Save hold settings.

To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, seeTroubleshooting.

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

C++

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

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

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#

For more information, see theCloud Storage C# API reference documentation.

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

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:

Go

For more information, see theCloud Storage Go API reference documentation.

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

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:

Java

For more information, see theCloud Storage Java API reference documentation.

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

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:

Node.js

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

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

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:

PHP

For more information, see theCloud Storage PHP API reference documentation.

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

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:

Python

For more information, see theCloud Storage Python API reference documentation.

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

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:

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

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

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:

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:
   {
   "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 either true to place the hold or false to release the hold.
3. 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.

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-12-09 UTC.