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 that gets returned from a specific method call, see the feature-specific documentation.

Get required roles

To get the permissions that you need to manage long-running operations in Cloud Storage, ask your administrator to grant you the Storage Admin (roles/storage.admin) role or the Storage Legacy Bucket Owner (roles/storage.legacyBucketOwner) role on the bucket or the project used to perform the underlying operation.

These predefined roles contain the following permissions, which are required to manage long-running operations in Cloud Storage:

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

For information about granting roles on buckets, see Use IAM with buckets. For information about granting roles on projects, see Manage access.

Get the details of a long-running operation

Command line

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
```

REST APIs

JSON API

Have gcloud CLI installed and initialized , in order to generate an access token for the Authorization header.

Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in the Authorization header.
Use cURL to call the JSON API with an operations.get request:
```
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/operations/OPERATION_ID"
```
Replace:
- BUCKET_NAME with the name of the bucket associated with the long-running operation.
- 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
```

If the request is successful, an operations resource is returned:

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

List the long-running operations in a bucket

Command line

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.

REST APIs

JSON API

Have gcloud CLI installed and initialized , in order to generate an access token for the Authorization header.

Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in the Authorization header.
Use cURL to call the JSON API with an operations.get request:
```
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/operations"
```
Replace:
- BUCKET_NAME with the name of the bucket associated with the long-running operations you want to list.

If the request is successful, you get a response similar to the following:

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

Cancel a long-running operation

Command line

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
```

REST APIs

JSON API

Have gcloud CLI installed and initialized , in order to generate an access token for the Authorization header.

Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in the Authorization header.
Use cURL to call the JSON API with an operations.post request:
```
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/operations/OPERATION_ID/cancel"
```
Replace:
- BUCKET_NAME with the name of the bucket associated with the long-running operation you want to cancel.
- 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
```

Metadata

Long-running operations have metadata associated with them. The following metadata identify properties of a long-running operation:

Create time: The time the long-running operation was created.
End time: The time the long-running operation finished running.
Update time: The time the long-running operation was last modified.
Type: The type of long-running operation invoked.
Requested cancellation: Indicates whether the user has requested cancellation of the long-running operation.
Progress percent: The estimated progress of the long-running operation, in percentage. A value of -1 means the progress is unknown.

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.