在 Cloud Storage 中使用长时间运行的操作

本页面介绍了如何在 Cloud Storage 中使用通过方法调用启动的长时间运行的操作。如需详细了解从特定方法调用返回的长时间运行的操作语义，请参阅特定于功能的文档。

获取所需角色

如需获得管理 Cloud Storage 中长时间运行的操作所需的权限，请让您的管理员为您授予存储桶或用于执行底层操作的项目的 Storage Admin (roles/storage.admin) 角色或 Storage Legacy Bucket Owner (roles/storage.legacyBucketOwner 角色。

这些预定义角色可提供以下权限，这些权限是管理 Cloud Storage 中长时间运行的操作所必需的：

  • storage.bucketOperations.cancel
  • storage.bucketOperations.get
  • storage.bucketOperations.list

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

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

命令行

如需获取长时间运行的操作的详细信息或检查其状态，请使用 gcloud storage operations describe 命令：

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

您需要将其中的：

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

  • OPERATION_ID 替换为长时间运行的操作的 ID，该 ID 会在您调用的方法的响应中返回。例如，调用 gcloud storage restore 会返回以下响应，长时间运行的操作 ID 为 BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP：

    Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

REST API

JSON API

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

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

  2. 使用 cURL，通过 operations.get 请求调用 JSON API：

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/operations/OPERATION_ID"

    您需要将其中的：

    • 将 BUCKET_NAME 替换为与长时间运行的操作关联的存储桶的名称。

    • OPERATION_ID 替换为长时间运行的操作的 ID，该 ID 会在您调用的方法的响应中返回。例如，调用 gcloud storage restore 会返回以下响应，长时间运行的操作 ID 为 BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP：

      Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

如果请求成功，系统会返回 operations 资源：

{
  "kind": "storage#operation",
  "name": "projects/_/buckets/bucket/operations/operation_id",
  "metadata": {
    "@type": OperationMetadataType*,
    metadata OperationMetadata*
  },
  "done": boolean,
  "response": {
    "@type": ResponseResourceType*,
    response ResponseResource*
  }
}

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

命令行

如需列出存储桶中长时间运行的操作，请使用 gcloud storage operations list 命令：

gcloud storage operations list gs://BUCKET_NAME

您需要将其中的：

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

REST API

JSON API

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

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

  2. 使用 cURL，通过 operations.get 请求调用 JSON API：

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/operations"

    您需要将其中的：

    • 将 BUCKET_NAME 替换为与您要列出的长时间运行的操作关联的存储桶的名称。

如果请求成功，您会收到类似于以下内容的响应：

{
  "kind": "storage#operations",
  "nextPageToken": string,
  "operations": [
    operations Resource
  ]
}

取消长时间运行的操作

命令行

如需取消长时间运行的操作，请使用 gcloud storage operations cancel 命令：

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

您需要将其中的：

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

  • OPERATION_ID 替换为长时间运行的操作的 ID，该 ID 会在您调用的方法的响应中返回。例如，调用 gcloud storage restore 会返回以下响应，长时间运行的操作 ID 为 BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP：

    Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

REST API

JSON API

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

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

  2. 使用 cURL，通过 operations.post 请求调用 JSON API：

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/operations/OPERATION_ID/cancel"

    您需要将其中的：

    • 将 BUCKET_NAME 替换为与要取消的长时间运行的操作关联的存储桶名称。

    • OPERATION_ID 替换为长时间运行的操作的 ID，该 ID 会在您调用的方法的响应中返回。例如，调用 gcloud storage restore 会返回以下响应，长时间运行的操作 ID 为 BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP：

      Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

元数据

长时间运行的操作具有关联的元数据。以下元数据用于标识长时间运行操作的属性：

  • 创建时间：长时间运行的操作的创建时间。

  • 结束时间：长时间运行的操作完成运行的时间。

  • 更新时间：上次修改长时间运行的操作的时间。

  • 类型：调用的长时间运行操作的类型。

  • 已请求取消：指示用户是否已请求取消长时间运行的操作。

  • 进度百分比：长时间运行的操作的估算进度，以百分比表示。值 -1 表示进度未知。

错误处理

长时间运行的操作通过异步 API 启动，需要的错误处理做法与同步 API 不同。与同步 API 不同，即使长时间运行的操作最终失败，对异步 API 调用的响应也可能指示成功。您应该解析响应正文中的长时间运行的操作元数据以确定 API 调用是否成功，而不是依赖于响应标头中返回的状态代码。

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

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