Идемпотентность
Сервисы Yandex Cloud поддерживают механизм идемпотентности. Идемпотентная операция — это операция, которая при многократном вызове возвращает один и тот же результат.
По умолчанию некоторые операции в API не являются идемпотентными. Например, операции, которые изменяют состояние ресурсов. Для обеспечения их идемпотентности, в запросах необходимо передавать заголовок Idempotency-Key. В заголовке следует указать UUID-строку — ее необходимо сформировать самостоятельно. У каждой операции должен быть свой UUID.
Idempotency-Key: <UUID>
Обратите внимание, рекомендуется использовать UUID версии 4.
Когда сервис получит запрос с заголовком Idempotency-Key, он проверит, была ли ранее создана операция с таким UUID. Если операция была создана, сервер вернет объект Operation с текущим статусом этой операции. Если операции с таким UUID не найдено, сервис начнет ее выполнение.
Примечание
Сервисы искусственного интеллекта Yandex Foundation Models, Yandex SpeechKit, Yandex Translate и Yandex Vision OCR не поддерживают идемпотентность даже с заголовком Idempotency-Key.
Примеры
На примерах ниже показано, как использовать механизм идемпотентности при работе с API Yandex Cloud.
Пример 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, то при повторной отправке запроса виртуальная машина не была бы остановлена.