Связаться с намиПодключиться

Объект Operation

Статья создана
Обновлена 26 августа 2024 г.

Каждая операция, которая изменяет состояние ресурса, приводит к созданию объекта Operation. Этот объект содержит информацию об операции: статус, идентификатор, время вызова и т. д.

С помощью объекта Operation вы можете:

Формат объекта Operation

Объект Operation содержит поля:

Поле Описание
id* string
Идентификатор операции. Генерируется на стороне сервиса.
created_at* google.protobuf.Timestamp
Время запуска операции. Указывается в формате RFC3339 (Timestamps).
created_by* string
Идентификатор пользователя, запустившего операцию.
modified_at* google.protobuf.Timestamp
Время последнего изменения ресурса. Указывается в формате RFC3339 (Timestamps).
done* bool
Статус операции. Принимает одно из двух значений:
true — операция завершена. Обратите внимание, операция считается завершенной, даже если в ходе ее выполнения возникла ошибка.
false — операция не завершена.
response google.protobuf.Any
Поле присутствует только в том случае, если операция была успешно завершена.

Для методов Create и Update поле response содержит представление созданного или измененного ресурса. Для других операций поле может содержать пустое сообщение google.protobuf.Empty (например, при удалении ресурса).

Поля response и error являются взаимоисключающими. Ответ не может одновременно содержать оба поля.
error google.rpc.Status
Сообщение об ошибке. Поле присутствует в том случае, если в ходе выполнения операции возникла ошибка.


Поле error может появиться в ответе до того, как операция была завершена: когда возникает ошибка, сервис сразу добавляет поле error в объект Operation. Одновременно с этим сервис начинает откатываться к предыдущему состоянию: завершает все запущенные процедуры и удаляет ресурсы, которые были созданы в ходе операции. Только когда сервис вернется к предыдущему состоянию, операция будет считаться завершенной и значение ее поля done будет выставлено в true.

Поля response и error являются взаимоисключающими. Ответ не может одновременно содержать оба поля.
metadata google.protobuf.Any
Метаданные операции. Обычно в поле содержится идентификатор ресурса, над которым выполняется операция. Если метод возвращает объект Operation, в описании метода приведена структура соответствующего ему поля metadata.
description string
Описание операции. Максимальная длина составляет 256 символов.

* Обязательное поле.

Отслеживание статуса операции

Узнать статус операции можно с помощью метода Get:

 // Возвращает объект Operation по заданному идентификатору.
 rpc Get (GetOperationRequest) returns (operation.Operation) {
   option (google.api.http) = {
     get: "/operations/{operation_id}"
   };
 }
 message GetOperationRequest {
   // Идентификатор операции.
   string operation_id = 1;
 }

Пример REST запроса на получение статуса операции:

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

Отмена операции

Отменить операцию можно с помощью метода Cancel:

 // Отменяет заданную операцию.
 rpc Cancel (CancelOperationRequest) returns (operation.Operation) {
   option (google.api.http) = {
     post: "/operations/{operation_id}:cancel"
   };
 }
 message CancelOperationRequest {
   // Идентификатор операции, которую нужно отменить.
   string operation_id = 1;
 }

Пример отмены операции в REST:

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

В ответ сервер вернет объект Operation, который будет содержать текущий статус отменяемой операции.

Отменять можно только те операции, которые изменяют состояние ресурсов. В справочниках все операции, для которых возможна отмена, отмечены явно.

Примечание

Метод Cancel работает по принципу Best Effort. Вызов метода не гарантирует, что операция будет отменена. Операция может находиться на стадии, когда отмена уже невозможна.

Просмотр списка операций

Для просмотра списка операций, которые были выполнены над заданным ресурсом, предназначен метод ListOperations. Метод поддерживает постраничное отображение результатов.

Обратите внимание, метод ListOperations позволяет получить список операций только над конкретным ресурсом, но не над категорией ресурсов. Например, вы не сможете посмотреть историю операций, которые производились над всеми дисками в вашем облаке.

Пример gRPC-описания метода ListOperations для просмотра списка операций над диском:

 // Выводит список операций, которые были произведены над заданным диском.
 rpc ListOperations (ListDiskOperationsRequest)
   returns (ListDiskOperationsResponse) {
     option (google.api.http) = {
       get: "/compute/v1/disks/{disk_id}/operations"
     };
   }
 message ListDiskOperationsRequest {
   // Идентификатор диска.
   string disk_id = 1;
   // Максимальное количество результатов на странице ответа.
   int64 page_size = 2;
   // Токен запрашиваемой страницы с результатами.
   string page_token = 3;
 }

 message ListDiskOperationsResponse {
   // Список операций, выполненных над заданным диском.
   repeated operation.Operation operations = 1;
   // Токен следующей страницы с результатами.
   string next_page_token = 2;
 }

Максимальное значение поля page_size равно 1000.

Пример запроса списка операций в REST:

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

Ответ сервера:

 {
   "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
      }
    },
    ...
   ]
 }
Предыдущая
Асинхронность
Следующая
Идемпотентность