Use long-running operations in Cloud Storage

This page describes how to use long-running operations that get initiated from using method calls in Cloud Storage. For detailed information about the semantics of a long-running operation, including which requests can be performed on the long-running operation, see the feature-specific documentation.

For general information on how to manage long-running operations, see the gcloud storage operations documentation.

Get the details of a long-running operation

To get the details or check the status of a long-running operation, use the gcloud storage operations describe command:

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

Replace:

• BUCKET_NAME with the name of the bucket that contains the long-running operation. For example, my-bucket.

• OPERATION_ID with the ID of the long-running operation, which is returned in the response of methods you call. For example, the following response is returned from calling gcloud storage restore and the long-running operation ID is BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

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

List the long-running operations in a bucket

To list the long-running operations in a bucket, use the gcloud storage operations list command:

gcloud storage operations list gs://BUCKET_NAME

Replace:

• BUCKET_NAME with the name of the bucket that contains the long-running operations. For example, my-bucket.

Cancel a long-running operation

Note: Cancelling a long-running operation is asynchronous and done at best-effort. A cancel request on a running long-running operation sets the requested cancellation field, but there's no guarantee that the request will be honored.

To cancel a long-running operation, use the gcloud storage operations cancel command:

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

Replace:

• BUCKET_NAME with the name of the bucket that contains the long-running operation. For example, my-bucket.

• OPERATION_ID with the ID of the long-running operation, which is returned in the response of methods you call. For example, the following response is returned from calling gcloud storage restore and the long-running operation ID is BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

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

Error handling

Long-running operations are initiated from asynchronous APIs and require different error handling practices than synchronous APIs. Unlike synchronous APIs, the response to asynchronous API calls can indicate success even if the long-running operation eventually fails. Instead of relying on the status code that gets returned in the response headers, you should parse the long-running operation metadata in the body of the response to determine whether an API call was successful.

For example, if you make a soft delete bulk restore request, it returns a successful HTTP status code (200 OK) even if an error occurs over the course of the operation. To check whether the bulk restore operation was successful, get the status of the long-running operation.

Note that the long-running operation APIs (Get, List, Cancel) are synchronous and return normal errors.