Идемпотентность

Сервисы Яндекс.Облака поддерживают механизм идемпотентности. Идемпотентная операция — это операция, которая при многократном вызове возвращает один и тот же результат.

По умолчанию некоторые операции в API не являются идемпотентными. Например, операции, которые изменяют состояние ресурсов. Для обеспечения их идемпотентности, в запросах необходимо передавать заголовок Idempotency-Key. В заголовке следует указать UUID-строку — ее необходимо сформировать самостоятельно. У каждой операции должен быть свой UUID.

Idempotency-Key: <UUID>

Обратите внимание, рекомендуется использовать UUID версии 4.

Когда сервис получит запрос с заголовком Idempotency-Key, он проверит, была ли ранее создана операция с таким UUID. Если операция была создана, сервер вернет объект Operation с текущим статусом этой операции. Если операции с таким UUID не найдено, сервис начнет ее выполнение.

Примеры

На примерах ниже показано, как использовать механизм идемпотентности при работе с API Яндекс.Облака.

Пример 1

Например, вы отправили запрос на запуск виртуальной машины:

POST /compute/v1/instances/e0m97h0gbq0foeuis03:start
HTTP/1.1
Host: compute.api.cloud.yandex.net
Idempotency-Key: c1700de3-b8cb-4d8a-9990-e4ebf052e9aa

Если снова отправить этот запрос c тем же Idempotency-Key, сервер не будет выполнять повторный запуск машины. Вместо этого сервер вернет объект Operation — он будет содержать статус операции, которая была вызвана при первом запросе.

Пример 2

Данный пример демонстрирует ситуацию, в которой возникает состояние гонки.

Пусть с одного клиента был отправлен запрос на остановку запущенной виртуальной машины. Заголовок Idempotency-Key при этом не указан.

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

В это время другой клиент заново запускает эту виртуальную машину (например, через UI-консоль).

Но когда у первого клиента появится доступ к интернету, он повторно отправит запрос на остановку машины. Так как заголовок Idempotency-Key не используется, виртуальная машина, которая необходима второму клиенту, будет остановлена.

Если бы в запросах на остановку машины первый клиент передавал Idempotency-Key, то при повторной отправке запроса виртуальная машина не была бы остановлена.