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 callinggcloud storage restore
and the long-running operation ID isBcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_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
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 callinggcloud storage restore
and the long-running operation ID isBcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_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.