使用软删除的对象

概览 设置

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

准备工作

如需管理和恢复存储桶中软删除的对象，请确保您具有该存储桶或包含该存储桶的项目的 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 与存储桶搭配使用。如需了解如何授予项目的角色，请参阅管理对项目的访问权限。

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

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

控制台

  1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。

    进入“存储桶”

  2. 在存储桶列表中，点击您要查看其软删除对象的存储桶的名称。此时会打开“存储桶详情”页面，其中“对象”标签页处于选中状态。

  3. 在显示列表中，选择仅软删除的对象。系统会显示软删除的对象列表。

命令行

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

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

替换以下内容：

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

REST API

JSON API

  1. 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。如需了解相关说明，请参阅 API 身份验证。

  2. 使用 cURL，通过 GET Object 请求调用 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?softDeleted=true"

    其中：

    • OAUTH2_TOKEN 是您在第 1 步中生成的访问令牌。
    • BUCKET_NAME 是相关存储桶的名称，例如 my-bucket。

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

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

控制台

  1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。

    进入“存储桶”

  2. 在存储桶列表中，点击您要查看其软删除版本的对象所在存储桶的名称。此时会打开“存储桶详情”页面，其中“对象”标签页处于选中状态。

  3. 点击您要查看其所有软删除的版本的对象。系统会显示对象详情页面。

  4. 点击版本历史记录标签页。

  5. 在显示列表中，选择仅软删除的对象。系统会显示该对象的所有软删除的版本列表。

命令行

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

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

替换以下内容：

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

REST API

JSON API

  1. 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。如需了解相关说明，请参阅 API 身份验证。

  2. 使用 cURL，通过 GET Object 请求调用 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?softDeleted=true"

    其中：

    • OAUTH2_TOKEN 是您在第 1 步中生成的访问令牌。
    • BUCKET_NAME 是相关存储桶的名称，例如 my-bucket。

恢复软删除的对象

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

控制台

  1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。

    进入“存储桶”

  2. 在存储桶列表中，点击您要恢复的软删除的对象所在存储桶的名称。此时会打开“存储桶详情”页面，其中“对象”标签页处于选中状态。

  3. 在显示列表中，选择仅软删除的对象。

  4. 导航到可能位于文件夹中的对象。

  5. 点击该软删除的对象。系统会显示对象详情页面。

  6. 在显示列表中，选择仅软删除的对象。系统会显示该对象的所有软删除的版本列表。

  7. 如需恢复对象的特定软删除的版本，请点击该对象版本旁边的恢复。此时会打开恢复对象版本窗格。

  8. 点击确认。

命令行

如需恢复对象的软删除的版本，请使用 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

  1. 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。如需了解相关说明，请参阅 API 身份验证。

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

    curl -X POST \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME/restore?generation=GENERATION_NUMBER"

    其中：

    • OAUTH2_TOKEN 是您在第 1 步中生成的访问令牌。
    • BUCKET_NAME 是相关存储桶的名称，例如 my-bucket。
    • OBJECT_NAME 是您要恢复的软删除对象的名称。例如 cat.jpeg。
    • GENERATION_NUMBER 是您要恢复的软删除对象的世代编号。如果您未指定世代编号，则系统会恢复最新版本。例如 1560468815691234。

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

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

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

控制台

  1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。

    进入“存储桶”

  2. 在存储桶列表中，找到包含要恢复的对象的存储桶。

  3. 点击与存储桶关联的存储桶溢出菜单 ()，然后选择创建恢复作业。

    此时会打开创建恢复作业窗格。

  4. 在选择要恢复的软删除对象部分，选择要从中恢复对象的删除期限。

  5. （可选）选择按 glob 模式过滤，然后输入 glob 模式以便仅恢复符合 glob 模式条件的对象。

  6. （可选）在恢复选项部分中切换其他恢复行为。

  7. 点击创建。

您可以点击 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

  1. 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。如需了解相关说明，请参阅 API 身份验证。

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

    curl -X POST \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/bulkRestore"

    其中：

    • OAUTH2_TOKEN 是您在第 1 步中生成的访问令牌。
    • BUCKET_NAME 是相关存储桶的名称，例如 my-bucket。

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

为批量恢复管理长时间运行的操作

Google Cloud CLI 中长时间运行的操作由操作名称（存储桶名称和操作 ID 的组合）标识。

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

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

如需了解有关如何管理长时间运行的操作的一般信息，请参阅 gcloud storage operations 文档。

获取长时间运行的操作的详细信息

使用 gcloud storage operations describe 命令：

gcloud storage operations describe projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

替换以下内容：

  • BUCKET_NAME：包含长时间运行的操作的存储桶的名称。例如 my-bucket。

  • OPERATION_ID：在批量恢复操作响应中返回的长时间运行的操作的 ID。

列出存储桶中长时间运行的操作

使用 gcloud storage operations list 命令：

gcloud storage operations list gs://BUCKET_NAME

替换以下内容：

  • BUCKET_NAME：包含长时间运行的操作的存储桶的名称。例如 my-bucket。

取消长时间运行的操作

使用 gcloud storage operations cancel 命令：

gcloud storage operations cancel projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

替换以下内容：

  • BUCKET_NAME：包含长时间运行的操作的存储桶的名称。例如 my-bucket。

  • OPERATION_ID：在批量恢复操作响应中返回的长时间运行的操作的 ID。

错误处理

长时间运行的操作是从异步 API 返回的，这些 API 需要的错误处理做法与同步 API 不同。与同步 API 不同，即使底层操作失败，返回长时间运行的操作的 API 也会成功。使用返回长时间运行的操作的 API 时，您会响应成功响应中返回的错误代码，而不是响应失败响应中返回的错误代码。

例如，如果您发出软删除批量恢复请求，则即使操作过程中发生错误，该请求也会返回成功的 HTTP 状态代码 (200 OK)。如需检查批量恢复操作是否成功，请查询长时间运行的操作的状态。

请注意，长时间运行的操作 API（Get、Create、Cancel）是同步的，会返回正常错误。

重试

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

后续步骤