Подготовить хост

POST /v1/infra/servers/:id/app-db/prepare

Запускает подготовку хоста галактики для работы с базой приложения: ставит недостающие пакеты и служебный образ для чтения базы. Подготовка идёт в фоне, её ход показывает статус подготовки хоста.

Параметры

Тело запроса может быть пустым или {}, не больше 4096 байт. Любое поле тела и любой параметр строки запроса отклоняются с 400 VALIDATION_ERROR.

Примеры

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

curl -X POST "https://vibecode.bitrix24.tech/v1/infra/servers/APP_ID/app-db/prepare" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

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

curl -X POST "https://vibecode.bitrix24.tech/v1/infra/servers/APP_ID/app-db/prepare" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

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

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${appId}/app-db/prepare`,
  {
    method: 'POST',
    headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
    body: '{}',
  }
)
const { success, data, error } = await res.json()
if (!success) throw new Error(error.code)
// 202 — подготовка идёт, опрашивайте GET по тому же адресу. 200 — хост уже готов
console.log(res.status, data.state)

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

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${appId}/app-db/prepare`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: '{}',
  }
)
const { success, data, error } = await res.json()

Поля ответа

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

Подготовка запущена, HTTP 202:

{
  "success": true,
  "data": {
    "state": "preparing",
    "missing": ["image"],
    "steps": [
      { "id": "disk", "state": "pending" },
      { "id": "python3", "state": "present" },
      { "id": "zstd", "state": "present" },
      { "id": "age", "state": "present" },
      { "id": "curl", "state": "present" },
      { "id": "image", "state": "pending" },
      { "id": "verify", "state": "pending" }
    ]
  }
}

Хост уже готов, HTTP 200:

{
  "success": true,
  "data": {
    "state": "ready",
    "steps": [
      { "id": "disk", "state": "done" },
      { "id": "python3", "state": "present" },
      { "id": "zstd", "state": "present" },
      { "id": "age", "state": "present" },
      { "id": "curl", "state": "present" },
      { "id": "image", "state": "present" },
      { "id": "verify", "state": "done" }
    ],
    "missing": []
  }
}

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

400 — в теле передано поле:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid preparation parameters"
  }
}

Ошибки

Причина неудачи самой подготовки приходит не ошибкой этого вызова, а в состоянии failed с data.errorCode в статусе подготовки.

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

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

• Что ставится на хост. Только отсутствующие python3, zstd, age, curl и закреплённый служебный образ для чтения базы. Пакеты ставятся из настроенных на хосте репозиториев Ubuntu с проверкой подписи. План установки проверяется перед каждым пакетом: обновлять и удалять уже установленные пакеты запрещено. Пакеты не запускают и не перезапускают службы, хост не перезагружается, приложение и Docker не перезапускаются. Нужно не меньше 6 ГиБ свободного места на корневом разделе и на разделе образов Docker. Подготовка ограничена 15 минутами.
• Подготовку выполняет платформа. Команды идут к хосту через служебный канал платформы. Ни вам, ни приложению доступ к хосту для этого не нужен.
• Повторный вызов. Пока подготовка идёт, вызов ничего не запускает и возвращает текущее состояние с HTTP 202. После failed вызов запускает подготовку заново, уже установленные компоненты пропускаются. Если ответ на запуск потерялся, сначала проверьте статус подготовки, а не повторяйте запуск автоматически.
• Подготовка запускается и без этого вызова. Новый хост галактики запускает её сам при первой загрузке. Создание копии базы — ручной, ежедневной или защитной — тоже запускает подготовку на неготовом хосте, если прошлая подготовка не закончилась кодом LOW_DISK, DPKG_BROKEN, APT_PLAN_UNSAFE или UNSUPPORTED_HOST. Этот вызов запускает её и после таких кодов.
• Длительность. На тестовом хосте, где пакеты уже стояли и загружался только служебный образ, подготовка заняла меньше 10 секунд.

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

• Получить статус подготовки хоста
• Получить сведения о базе
• Создать копию базы
• База данных приложения