#Снять зависший лок

DELETE /v1/infra/servers/:id/lock

Принудительно снимает зависший лок операции на сервере. Используйте, когда `/exec` или `/deploy` оборвались со стороны клиента (потеряно соединение, локальный таймаут), но на сервере всё ещё активен лок и последующие вызовы возвращают EXEC_BUSY. Эндпоинт всегда возвращает 200: если лок был — снят и в ответе released: true, если его не было — вернётся released: false (тоже успех).

Используйте осторожно. Снятие лока активной операции может привести к непредсказуемому состоянию сервера — одновременно запущенные /exec и /deploy могут конкурировать за файлы и systemd-юниты.

#Параметры

Параметр В Тип Обяз. Описание
id path string (UUID) да ID сервера

Тело запроса пустое.

#Примеры

#curl — личный ключ

Terminal 
curl -X DELETE -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/lock

#curl — OAuth-приложение

Terminal 
curl -X DELETE -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/lock

#JavaScript — личный ключ

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/lock`,
  {
    method: 'DELETE',
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  }
)
const { data } = await res.json()

if (data.released) {
  console.log(`Снят лок ${data.operation}, держался ${data.ageMs}ms, до истечения было ${data.expiresInMs}ms`)
} else {
  console.log(data.message)  // "No active lock on this server"
}

#JavaScript — OAuth-приложение

javascript 
await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/lock`,
  {
    method: 'DELETE',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)

#Поля ответа

Поле Тип Описание
success boolean Всегда true при вызове на существующем сервере
data.released boolean true — был активный лок, и он снят. false — лок отсутствовал
data.operation string Тип снятой операции: "exec" или "deploy". Присутствует только при released: true
data.ageMs number Сколько миллисекунд лок был активен. Присутствует только при released: true
data.expiresInMs number Через сколько миллисекунд лок истёк бы сам. Присутствует только при released: true
data.message string Сообщение "No active lock on this server". Присутствует только при released: false

#Пример ответа

Лок был — снят:

JSON 
{
  "success": true,
  "data": {
    "released": true,
    "operation": "deploy",
    "ageMs": 320000,
    "expiresInMs": 580000
  }
}

Лока не было:

JSON 
{
  "success": true,
  "data": {
    "released": false,
    "message": "No active lock on this server"
  }
}

#Пример ответа при ошибке

404 — сервер не найден:

JSON 
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Server not found"
  }
}

#Ошибки

HTTP Код Описание
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Неверный или просроченный API-ключ
404 NOT_FOUND Сервер не существует, удалён или принадлежит другому API-ключу
429 RATE_LIMIT_EXCEEDED Превышен общий лимит запросов платформы

Полный список общих ошибок API — Ошибки.

#Известные особенности

  • Один лок на сервер. Защита от гонок между /exec и /deploy — они делят один общий лок. Невозможно заблокировать отдельную команду.
  • Автосброс при нормальном завершении. Успех или ошибка /exec//deploy снимают лок сами. DELETE /lock нужен только когда клиент оборвал соединение до завершения или таймаут агента прошёл без отправки финального события.
  • TTL лока — автоистечение без вызова. /exec ставит лок на timeout + 30 + 60 секунд. /deploy — на 15 минут. Даже без DELETE /lock зависший лок истечёт сам.
  • released: false — это успех, не ошибка. Эндпоинт не возвращает 404 при отсутствии лока, потому что идея в том, чтобы «гарантировать, что лока нет». Клиенту не важно, был он или не был.
  • Работает в любом режиме сервера. В отличие от большинства Deploy API эндпоинтов, DELETE /lock не требует BLACKHOLE — лок держится в памяти платформы, не зависит от агента.

#Смотрите также