使用软删除的对象

概览设置

本页面介绍了如何列出、访问和恢复软删除的对象。

准备工作

如需完成本页面上的任务，请确保您拥有存储桶或包含该存储桶的项目的 Storage Admin (roles/storage.admin) IAM 角色。此预定义角色可提供为存储桶管理和恢复软删除所需的权限。

如需查看所需的确切权限，请展开所需权限部分：

所需权限

storage.buckets.get
storage.buckets.update
storage.buckets.list
- 如果您计划使用 Google Cloud 控制台执行本页面上的说明，则需要此权限。
storage.objects.restore
storage.objects.create
storage.objects.delete
- 如果恢复对象会导致现有对象被覆盖，则需要此权限。
storage.buckets.restore
- 如果您要批量恢复存储桶中软删除的对象，则需要此权限。
storage.bucketOperations.*
- 长时间运行的操作需要此权限。

如需了解如何授予存储桶的角色，请参阅将 IAM 与存储桶搭配使用。如需了解如何授予项目的角色，请参阅管理对项目的访问权限。

列出存储桶中所有软删除的对象

您可以列出存储桶中所有软删除的对象。

控制台

在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。
进入“存储桶”
在存储桶列表中，点击您要查看其软删除对象的存储桶的名称。此时会打开“存储桶详情”页面，其中“对象”标签页处于选中状态。
在显示列表中，选择仅软删除的对象。系统会显示软删除的对象列表。

命令行

如需显示存储桶中所有软删除的对象列表，请将 gcloud storage ls 命令与 --soft-deleted 和 --recursive 标志结合使用：

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

替换以下内容：

BUCKET_NAME：存储桶的名称。例如 my-bucket。

REST API

JSON API

安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。

或者，您可以使用 OAuth 2.0 Playground 创建访问令牌，并将其包含在 Authorization 标头中。

使用 cURL，通过列出对象请求（其中使用了 ?softDeleted 查询参数）调用 JSON API：

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"

其中 BUCKET_NAME 是相关存储桶的名称，例如 my-bucket。

查看对象的所有软删除的版本

您可以查看存储桶中特定对象的所有软删除的版本。

控制台

在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。
进入“存储桶”
在存储桶列表中，点击您要查看其软删除版本的对象所在存储桶的名称。此时会打开“存储桶详情”页面，其中“对象”标签页处于选中状态。
点击您要查看其所有软删除的版本的对象。系统会显示对象详情页面。
点击版本历史记录标签页。
在显示列表中，选择仅软删除的对象。系统会显示该对象的所有软删除的版本列表。

命令行

如需显示存储桶中对象的所有软删除的版本列表，请使用 gcloud storage ls 命令：

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

替换以下内容：

BUCKET_NAME：存储桶的名称。例如 my-bucket。
OBJECT_NAME：您要查看其所有版本的对象的名称。

REST API

JSON API

安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。

或者，您可以使用 OAuth 2.0 Playground 创建访问令牌，并将其包含在 Authorization 标头中。
使用 cURL，通过列出对象请求（其中使用了 ?softDeleted 查询参数）调用 JSON API：
```
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"
```
请替换以下内容：
- BUCKET_NAME：存储桶的名称。例如 my-bucket。
- OBJECT_NAME：您要查看所有版本的对象的名称。

恢复软删除的对象

您可以恢复存储桶中软删除的对象的特定版本。

控制台

在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。
进入“存储桶”
在存储桶列表中，点击您要恢复的软删除的对象所在存储桶的名称。此时会打开“存储桶详情”页面，其中“对象”标签页处于选中状态。
在显示列表中，选择仅软删除的对象。
导航到可能位于文件夹中的对象。
点击该软删除的对象。系统会显示对象详情页面。
在显示列表中，选择仅软删除的对象。系统会显示该对象的所有软删除的版本列表。
如需恢复对象的特定软删除的版本，请点击该对象版本旁边的恢复。此时会打开恢复对象版本窗格。
点击确认。

命令行

如需恢复对象的软删除的版本，请使用 gcloud storage restore 命令：

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

替换以下内容：

BUCKET_NAME：存储桶的名称。例如 my-bucket。
OBJECT_NAME：您要查看其所有版本的对象的名称。
GENERATION_NUMBER：您要恢复的软删除对象的世代编号。如果您未指定世代编号，则系统会恢复最新版本。例如 1560468815691234。

如需了解用于批量恢复多个对象的其他选项（包括使用 all-versions 标志恢复对象的所有版本），请参阅 gcloud storage restore 参考文档。

REST API

JSON API

安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。

或者，您可以创建访问令牌（使用 OAuth 2.0 Playground），并将其包含在 Authorization 标头中。
使用 cURL，通过 POST Object 请求调用 JSON API：
```
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"
```
其中：
- BUCKET_NAME 是相关存储桶的名称，例如 my-bucket。
- OBJECT_NAME 是您要恢复的软删除对象的名称。例如 cat.jpeg。
- GENERATION_NUMBER 是您要恢复的软删除对象的世代编号。如果您未指定世代编号，则系统会恢复最新版本。例如 1560468815691234。

批量恢复存储桶中软删除的对象

如果您要恢复大量对象，或者不知道要恢复的特定对象，请使用批量恢复操作。请注意，批量恢复操作是异步进行的，在某些情况下，可能需要一个小时或更长时间才能开始。

批量恢复操作会对存储桶启动长时间运行的操作。您可以使用 Google Cloud CLI 获取和列出长时间运行的操作，以便可在批量恢复操作正在进行期间查看其详细信息和状态。

控制台

在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。
进入“存储桶”
在存储桶列表中，找到包含要恢复的对象的存储桶。
点击与存储桶关联的存储桶溢出菜单 ()，然后选择创建恢复作业。

此时会打开创建恢复作业窗格。
在选择要恢复的软删除对象部分，选择要从中恢复对象的删除期限。
（可选）选择按 glob 模式过滤，然后输入 glob 模式以便仅恢复符合 glob 模式条件的对象。
（可选）在恢复选项部分中切换其他恢复行为。
点击创建。

您可以点击 Google Cloud 控制台标题中的通知按钮 () 来跟踪批量恢复操作的进度。

命令行

如需使用批量恢复操作恢复存储桶中的所有对象，请使用 gcloud storage restore 命令。

以下命令会执行批量恢复操作，以异步恢复在特定时间段内删除的存储桶的所有对象：

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

替换以下内容：

BUCKET_NAME：存储桶的名称。例如 my-bucket。
DELETED_AFTER_TIME：可选参数，用于指定对象在此之后恢复的日期。例如 2022-12-01。
DELETED_BEFORE_TIME：可选参数，用于指定对象在此之前恢复的日期。例如 2022-12-21。

如果成功，该命令会返回与批量恢复操作关联的长时间运行的操作的 ID。您可以获取长时间运行的操作的详细信息，也可以取消长时间运行的操作以在批量恢复操作完成之前予以停止。如需了解详情，请参阅使用长时间运行的操作。

REST API

JSON API

安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。

或者，您可以创建访问令牌（使用 OAuth 2.0 Playground），并将其包含在 Authorization 标头中。

使用 cURL，通过 POST Object 请求调用 JSON API：

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"

其中 BUCKET_NAME 是相关存储桶的名称，例如 my-bucket。

如果成功，该命令会返回与批量恢复操作关联的长时间运行的操作的 ID。您可以获取长时间运行的操作的详细信息，也可以取消长时间运行的操作以在批量恢复操作完成之前予以停止。如需了解详情，请参阅使用长时间运行的操作。

为批量恢复使用长时间运行的操作

批量恢复操作会启动长时间运行的操作。您可以获取和列出长时间运行的操作以查看批量恢复操作的详细信息和状态，也可以删除长时间运行的操作以取消正在进行的批量恢复操作。

如需了解如何使用从 Cloud Storage 中的操作发起的长时间运行的操作（例如批量恢复操作），请参阅使用长时间运行的操作。

以下示例展示了从批量恢复操作返回的长时间运行的操作：

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"
  }
}

重试

默认情况下，异步软删除 API 具有幂等性。因此，您可以放心地重试异步软删除 API 调用，而不用担心意外修改资源。

后续步骤

详细了解软删除。