Operation object

Each operation that changes the state of a resource results in the creation of the object Operation. This object contains information about the operation: its status, ID, call time, and so on.

Using the Operation object, you can:

Format of the Operation object

The Operation object contains the following fields:

Field Description
id* string
Operation ID. Generated on the service side.
created_at* google.protobuf.Timestamp
Operation start time. Specified in the RFC3339 (Timestamps) format.
created_by* string
ID of the user who started the operation.
modified_at* google.protobuf.Timestamp
The time when the resource was last updated. Specified in the RFC3339 (Timestamps) format.
done* bool
Operation status. Can take one of the following two values:
true — the operation is completed. Note that the operation is considered completed even if an error occurred during its execution.
false — the operation is not completed.
response google.protobuf.Any
This field is present only if the operation completed successfully.

For the Create and Update methods, the response field contains a view of the created or updated resource. For other operations, the field may contain an empty message, google.protobuf.Empty, for example, when deleting a resource.

The response and error fields are mutually exclusive. A response cannot contain both of the fields at the same time.
error google.rpc.Status
Error message. This field is present if an error occurrs during the operation.


The error field may appear in the response before the operation is completed: when an error occurs, the service immediately adds the error field to the Operation object. At the same time, the service starts rolling back to the previous state: it aborts all running procedures and deletes the resources created during the operation. Only when the service returns to the previous state will the operation be considered completed and the value of its done field will be set to true.

The response and error fields are mutually exclusive. A response cannot contain both of the fields at the same time.
metadata google.protobuf.Any
Operation metadata. This field usually contains the ID of the resource the operation is being performed on. If the method returns the Operation object, the method description contains the structure of the corresponding metadata field.
description string
Operation description. The maximum length is 256 characters.

* Required field.

Operation status monitoring

To find out the operation status, use the Get method:

 // Returns the Operation object by the specified ID.
 rpc Get (GetOperationRequest) returns (operation.Operation) {
   option (google.api.http) = {
     get: "/operations/{operation_id}"
   };
 }
 message GetOperationRequest {
   // Operation ID.
   string operation_id = 1;
 }

Sample REST request used to get the operation status:

GET https://operation.api.cloud.yandex.net/operations/fcmq0j5033e516c56ctq

Canceling an operation

To cancel an operation, use the Сancel method:

 // Cancels the specified operation.
 rpc Cancel (CancelOperationRequest) returns (operation.Operation) {
   option (google.api.http) = {
     post: "/operations/{operation_id}:cancel"
   };
 }
 message CancelOperationRequest {
   // ID of the operation to cancel.
   string operation_id = 1;
 }

Example of canceling an operation in the REST API:

POST https://operation.api.cloud.yandex.net/operations/a3s17h9sbq5asdgss12:cancel

In response, the server returns the Operation object with the current status of the operation being canceled.

You can only cancel operations that change the state of a resource. In the references, all operations that can be canceled are marked explicitly.

Note

The Сancel method works on a best effort basis. Calling the method does not guarantee that the operation will be canceled. The operation may be at a stage when no cancellation is possible.

Viewing a list of operations

To view a list of operations that were performed on the specified resource, use the ListOperations method. The method supports result pagination.

Note that the ListOperations method returns a list of operations only for a specific resource, but not for a category of resources. For example, you cannot view the history of operations performed on all disks in your cloud.

Sample gRPC description of the method for operations performed on a disk:

 // Returns a list of operations performed on the specified disk.
 rpc ListOperations (ListDiskOperationsRequest)
   returns (ListDiskOperationsResponse) {
     option (google.api.http) = {
       get: "/compute/v1/disks/{disk_id}/operations"
     };
   }
 message ListDiskOperationsRequest {
   // Disk ID.
   string disk_id = 1;
   // Maximum number of results per response page.
   int64 page_size = 2;
   // Token of the requested result page.
   string page_token = 3;
 }

 message ListDiskOperationsResponse {
   // List of operations performed on the specified disk.
   repeated operation.Operation operations = 1;
   // Token for the next result page.
   string next_page_token = 2;
 }

Sample REST request for a list of operations:

GET https://compute.api.cloud.yandex.net/compute/v1/disks/e0m97h0gbq0foeuis03/operations

Server response:

 {
   "operations": [
     {
       "id": "fcmq0j5033e516c56ctq",
       "createdAt": "2018-08-29T18:31:15.311Z",
       "createdBy": "v1swrh5sbqs5sdgss15",
       "done": true,
       "metadata": {
         "@type": "type.googleapis.com/yandex.cloud.compute.v1.CreateDiskMetadata",
         "diskId": "sfg36d6sbq5asdgfs01"
       },
      "response": {
        "@type": "type.googleapis.com/yandex.cloud.compute.v1.Disk",
        "id": "sfg36d6sbq5asdgfs01",
        "folderId": "a3s17h9sbq5asdgss12",
        "name": "disk-1",
        "description": "Test disk",
        "zoneId" : "ru-central1-a",
        "typeId" : "network-nvme",
        "size" : 10737418240 
      }
    },
    ...
   ]
 }