Console
Start free

Use soft-deleted objects

Overview Setup

This page describes how to list, access, and restore soft-deleted objects.

Before you begin

To get the permissions that you need to list, access, and restore soft-deleted objects, ask your administrator to grant you the Storage Admin (roles/storage.admin) IAM role on the bucket, managed folder, or project.

This predefined role contains the permissions required to list, access, and restore soft-deleted objects. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to list, access, and restore soft-deleted objects:

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.

In order to manage long-running operations that get initiated from soft delete methods, you might need additional roles and permissions. See required roles for long-running operations to learn more.

List all of the soft-deleted objects in a bucket

Use the following instructions to list all of the soft-deleted objects in 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 you want to view the soft-deleted objects of. The Bucket details page opens with the Objects tab selected.

  3. In the Show list, select Soft-deleted objects only. A list of soft-deleted objects is displayed.

Command line

To display a list of all the soft-deleted objects in a bucket, use the gcloud storage ls command with the --soft-deleted flag and the ** wildcard. Note that you might need to surround the wildcard expression with quotes.

  gcloud storage ls gs://BUCKET_NAME/** --soft-deleted

Replace the following:

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 a request to list objects that uses the ?softDeleted query parameter:

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o?softDeleted=true"

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

    • View all of the soft-deleted versions of an object

    Use the following instructions to view all the soft-deleted versions of a specific 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 contains the object you want to view soft-deleted versions of. The Bucket details page opens with the Objects tab selected.

    3. Click the object that you want to view all the soft-deleted versions of. The Object details page displays.

    4. Click the Version History tab.

    5. In the Show list, select Soft-deleted objects only. A list of all the soft-deleted versions for that object displays.

    Command line

    To display a list of all the soft-deleted versions of an object in a bucket, use the gcloud storage ls command:

      gcloud storage ls gs://BUCKET_NAME/OBJECT_NAME --soft-deleted

    Replace the following:

    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 a request to list objects that uses the ?softDeleted query parameter:

    curl -X GET \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o?matchGlob=OBJECT_NAME&softDeleted=true"

    Replace the following:

    • Restore a soft-deleted object

    You can restore a specific version of a soft-deleted object in your bucket. Note that you cannot restore objects in a soft-deleted bucket. To restore objects in a soft-deleted bucket, you must first restore the soft-deleted bucket.

    Use the following instructions to restore a soft-deleted 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 soft-deleted objects that you want to restore. The Bucket details page opens with the Objects tab selected.

    3. In the Show list, select Soft-deleted objects only.

    4. Navigate to the object, which may be located in a folder.

    5. Click the soft-deleted object. The Object details page displays.

    6. In the Show list, select Soft-deleted objects only. A list of all the soft-deleted versions of that object displays.

    7. To restore a specific soft-deleted version of an object, click Restore next to that object version. The restore object version pane opens.

    8. Click Confirm.

    Command line

    To restore a soft-deleted version of an object, use the gcloud storage restore command:

      gcloud storage restore gs://BUCKET_NAME/OBJECT_NAME#GENERATION_NUMBER

    Replace the following:

    For additional options for restoring multiple objects in bulk, including restoring all versions of an object with the all-versions flag, see the gcloud storage restore reference.

    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 a POST Object request:

    curl -X POST \
  -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/restore?generation=GENERATION_NUMBER"

    Where:

    • Bulk restore soft-deleted objects in a bucket

    If you want to restore a large number of objects, or don't know the specific objects that you want to restore, use a bulk restore operation. Note that bulk restore operations occur asynchronously and can, in some cases, take an hour or more to begin.

    Bulk restore operation initiates a long-running operation on a bucket. You can use the Google Cloud CLI to get and list long-running operations so you can view the details and status of the bulk restore operation while it's in progress.

    Use the following instructions to bulk restore soft-deleted objects in 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, find the bucket that contains the objects you want to restore.

    3. Click the Bucket overflow menu () associated with the bucket and select Create restore job.

      The Create a restore job pane opens.

    4. In the Choose which soft-deleted objects to restore section, select the time range that you want to restore objects from.

    5. Optional: To restore only the objects that match a glob pattern, select Filter by glob pattern and then enter a glob pattern.

    6. Optional: Specify additional restore behaviors in the Restore options section.

    7. Click Create.

    You can track the progress of your bulk restore operation by clicking the Notifications button () in the Google Cloud console header.

    Command line

    To use the bulk restore operation to restore all objects in a bucket, use the gcloud storage restore command.

    For example, the following command performs bulk restore operation to asynchronously restore all the objects of the bucket that were deleted during a specific time period:

      gcloud storage restore gs://BUCKET_NAME/** \
      --async --deleted-after-time=DELETED_AFTER_TIME \
      --deleted-before-time=DELETED_BEFORE_TIME

    Replace the following:

    For additional options that you can use to filter the objects to be bulk restored, see the gcloud storage restore reference.

    If successful, the command returns the ID of the long-running operation associated with the bulk restore operation. You can get the details of the long-running operation or cancel the long-running operation to stop the bulk restore operation before it completes. For more information, see Use long-running operations.

    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 a POST Object request:

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/bulkRestore"

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

    • If successful, the command returns the ID of the long-running operation associated with the bulk restore operation. You can get the details of the long-running operation or cancel the long-running operation to stop the bulk restore operation before it completes. For more information, see Use long-running operations.

    Use long-running operations for bulk restore

    The bulk restore operation for objects initiates a long-running operation. You can get and list long-running operations in order to view the details and status of a bulk restore operation, or delete a long-running operation in order to cancel a bulk restore operation while it's in progress.

    For instructions on using long-running operations that get initiated from operations in Cloud Storage, such as the bulk restore operation, see Use long-running operations.

    The following example shows a long-running operation that's returned from a bulk restore operation:

    done: false
{
  "kind": "storage@operation",
  "name": "projects/_/buckets/my-bucket/operations/CiQyODRlMTY0My0wNGExLTQ3MWItOTE2Zi1hZmQ0ZmM4ZDc4MjQQAg",
  "metadata": {
    "@type": "type.googleapis.com/google.storage.v2.BulkRestoreObjectsMetadata",
    "commonMetadata": {
      "type": "bulk-restore-objects",
      "createTime": "2023-10-20T21:08:11.289Z",
      "updateTime": "2023-10-20T21:18:37.583Z",
      "endTime": "2023-10-20T21:18:37.583Z",
      "requestedCancellation": false,
      "progressPercent": -1,
    },
    "allow_overwrite": false,
    "matchGlobs": ["*"],
    "succeededCount": "0",
    "failedCount": "0",
    "skippedCount": "0",
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.storage.v2.BulkRestoreObjectsResponse"
  }
}

    What's next