Operation object

Written by

Improved by

Updated at October 1, 2024

Operation object format
Operation status monitoring
Canceling an operation
Viewing a list of operations

Each operation that changes the state of a resource causes an Operation object to be created. This object contains information about the operation: its status, ID, call time, and so on.

With the Operation object, you can:

Monitor the status of operations with indefinite duration. For example, starting a VM or attaching a disk.
Cancel operations.
View a list of operations that were performed on the specified resource.

Field	Description
`id`*	string Operation ID. Generated on the service side.
`created_at`*	google.protobuf.Timestamp Operation start time. Uses RFC3339 (Timestamps) format.
`created_by`*	string ID of the user who started the operation.
`modified_at`*	google.protobuf.Timestamp Resource last update time. Uses RFC3339 (Timestamps) format.
`done`*	bool Operation status. Can take one of the two values: true: Operation completed. Note that the operation is considered completed even if an error occurred during its execution. false: Operation not completed.
`response`	google.protobuf.Any This field is only present if the operation was 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), e.g., when deleting a resource. The `response` and `error` fields are mutually exclusive. A response cannot contain both fields at the same time.
`error`	google.rpc.Status Error message. This field is present if an error occurs 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, the operation will be considered completed and its `done` field will be set to true. The `response` and `error` fields are mutually exclusive. A response cannot contain both 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.

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 Cancel 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 will return 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 Cancel 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 cancellation is no longer possible.

Viewing a list of operations

To view a list of operations that were performed on a given 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, not resource category. For example, you cannot view the history of operations performed on all disks in your cloud.

Sample gRPC description of the ListOperations method for viewing a list of 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;
 }

The maximum page_size field value is 1000.

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
      }
    },
    ...
   ]
 }

Operation object