Обзор

Методы справочника API сгруппированы по ресурсам. Чтобы выполнить операцию над ресурсом, сделайте RPC-вызов. Подробнее в документации Концепции API Yandex Cloud.

Обработка ответов мутирующих операцийОбработка ответов мутирующих операций

Все операции, которые изменяют состояние ресурса, имеют асинхронную сигнатуру. При вызове таких операций сервер возвращает объект Operation.

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

Если во время выполнения асинхронной операции возникла ошибка, сервер отменяет все запущенные процедуры. В объект Operation добавляется поле error с описанием ошибки.

Когда в ответ на запрос возвращается объект Operation, необходимо:

• проверить, что поле done=true;
• проверить, что в поле error нет ошибок;
• получить ответ из поля response.

Пример ошибки:

code: 6
message: "ALREADY_EXISTS: Name must be uniq in parentId"

Обработка ошибокОбработка ошибок

Если возникает ошибка, Monitoring API возвращает gRPC status != OK. В теле ответа содержится подробное описание ошибки в следующем формате:

code: <number> код ошибки
message: <string>  текст ошибки

Пример сообщения об ошибке:

code: 6
message: "ALREADY_EXISTS: Name must be uniq in parentId"

На данный момент нет фиксированного списка кодов ошибок, поэтому поле code зарезервировано для использования в следующих версиях Monitoring.

Конфликты при обновлении объектовКонфликты при обновлении объектов

Чтобы разрешать конфликты при обновлении объектов, используется необязательное поле etag. Его можно передавать в мутирующих операциях и получать с помощью метода Get. Объект изменится, если во время выполнения запроса не был изменен другим параллельным запросом и etag в операции совпадает со значением сервера. Если возникла ошибка, необходимо получить новый etag и повторить операцию.

etag — опциональное поле. Если оно не передано, применяется политика last-write-wins.