本页面介绍了如何在 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
安装并初始化 gcloud CLI,以便为
Authorization
标头生成访问令牌。或者,您可以使用 OAuth 2.0 Playground 创建访问令牌,并将其包含在
Authorization
标头中。使用
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
安装并初始化 gcloud CLI,以便为
Authorization
标头生成访问令牌。或者,您可以使用 OAuth 2.0 Playground 创建访问令牌,并将其包含在
Authorization
标头中。使用
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
安装并初始化 gcloud CLI,以便为
Authorization
标头生成访问令牌。或者,您可以使用 OAuth 2.0 Playground 创建访问令牌,并将其包含在
Authorization
标头中。使用
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)是同步的,会返回正常错误。