К содержимому

Защита от параллельных изменений

Обновлено

Если настройку или источники проекта изменили после вашего чтения, API должен обнаружить конфликт, прежде чем применить ваше обновление. Для этого используются заголовки ETag и If-Match.

Прочитать, изменить, проверить

  1. Прочитайте ресурс обычным GET и сохраните сильный ETag из заголовка ответа.

  2. Подготовьте изменение на основе прочитанных данных.

  3. Передайте сохранённое значение целиком, включая кавычки, в If-Match запроса обновления. Для фоновой операции также нужны reason и Idempotency-Key.

  4. При 412 перечитайте ресурс и заново сформируйте изменение. Не подставляйте новый ETag в прежнее изменение без проверки данных.

Значения ETag непрозрачны и чувствительны к регистру. Не вычисляйте их самостоятельно. Слабое значение начинается с W/: оно подходит для проверки повторного чтения, но не разрешает изменение.

Ответ на обновление

Что сделать

428

Добавить обязательный If-Match

400

Исправить синтаксис заголовка; If-Match: * для изменений не поддерживается

412

Перечитать ресурс и проверить, как совместить изменения

202 Accepted

Сохранить ID операции и дождаться результата

If-Match может содержать список заключённых в кавычки значений через запятую. Достаточно одного совпадающего сильного ETag. Корректный список без такого совпадения, в том числе список только из слабых значений, возвращает 412.

Какие чтения возвращают ETag

Настройки кабинета и конфигурация аналитики возвращают сильный ETag. Для источников проекта правила зависят от формы ответа:

Запрос источников

ETag

view=edit, явно выбран один projectIds и проект присутствует в ответе

Сильный, пригоден для обновления этого проекта

Остальные страницы view=edit

Слабый, не пригоден для обновления

view=read

Не возвращается

Чтобы подготовить изменение источников, сначала запросите один конкретный проект:

curl --include \
  'https://api.alitos.io/v1/external/cabinets/123456789/projects/sources?view=edit&projectIds=987654321' \
  --header "Authorization: Bearer ${ALITOS_EXTERNAL_JWT}"

Замените идентификаторы значениями из вашей интеграции. Если проект отсутствует, не используйте ETag страницы как разрешение на его изменение.

Сильный ETag источников имеет вид "source-edit-v1.<число возвращённых источников>.<sha256>". Он учитывает возвращённые метаданные проекта и источники. Формат приведён для справки: клиент сохраняет заголовок целиком и не разбирает его.

Поле sourcesFingerprint в теле ответа — старый отпечаток только источников. Он остаётся совместимым валидатором для старых клиентов, но не заменяет полный ETag нового клиента. Не подменяйте одно значение другим.

Не получать неизменившийся ответ повторно

При повторном чтении настроек, конфигурации аналитики или источников в view=edit передайте сохранённый ETag в If-None-Match. При совпадении API вернёт 304, текущий ETag и пустое тело ответа.

Здесь допустимы сильные и слабые значения, список значений и *. Сравнение для If-None-Match слабое. Если также передан If-Match, он проверяется первым: его несовпадение даёт 412. Некорректный условный заголовок даёт 400.

Условный запрос не обходит авторизацию: доступ и текущее состояние проверяются до сравнения ETag. Сохранённый ETag не гарантирует, что доступ к кабинету сохранился.

Точные заголовки и ответы описаны в OpenAPI.