Yandex Cloud
  • Сервисы
  • Решения
  • Почему Yandex Cloud
  • Сообщество
  • Тарифы
  • Документация
  • Связаться с нами
Подключиться
Language / Region
Проект Яндекса
© 2023 ООО «Яндекс.Облако»
Концепции API Yandex Cloud
  • Основные принципы
  • Ресурсы
    • Идентификация ресурсов
    • Стандартные поля
  • Методы API
    • Обзор
    • Эндпоинты API
    • Стандартные методы
    • Дополнительные методы
    • Пагинация
    • Обработка ошибок
  • Работа с операциями
    • Обзор
    • Асинхронность
    • Объект Operation
    • Идемпотентность
  1. Работа с операциями
  2. Идемпотентность

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

Статья создана
Yandex Cloud
  • Примеры
    • Пример 1
    • Пример 2

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

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

Idempotency-Key: <UUID>

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

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

Примеры

На примерах ниже показано, как использовать механизм идемпотентности при работе с 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, то при повторной отправке запроса виртуальная машина не была бы остановлена.

Была ли статья полезна?

Language / Region
Проект Яндекса
© 2023 ООО «Яндекс.Облако»
В этой статье:
  • Примеры
  • Пример 1
  • Пример 2