Перейти до вмісту

Публічний API

← Назад до індексу документації

Невеликий HTTP API лише для читання для отримання статусу сервера ззовні панелі: інформаційна панель статусу, монітор часу роботи, бот Discord, правило домашньої автоматизації. Він обслуговується самою панеллю та повертає ті самі дані в реальному часі, які показують власні сторінки панелі (з кешу в пам’яті), тому опитування його ніколи не торкається Docker.

Він вимкнений, доки адміністратор його не використає, і контролюється адміністратором. Нічого не відображається, доки не існує токен.

Налаштування → Публічний API → Новий ключ. Надайте йому назву, виберіть, що він може бачити (усі сервери або певний підмножина) та, за бажанням, дату закінчення терміну дії. Повний ключ (токен Bearer) відображається один раз у діалоговому вікні; скопіюйте його зараз, оскільки пізніше зберігається лише коротка префікс для ідентифікації у списку.

Налаштування Публічного API

Створення першого ключа автоматично вмикає API (перемикач Дозволити зовнішнім програмам читати статус є елементом керування паузою: вимкніть його, щоб припинити обслуговування без скасування будь-яких ключів). Скасуйте ключ з тієї ж таблиці в будь-який час; клієнти, які його використовують, негайно втрачають доступ.

Токени зберігаються як хеш SHA-256 (ніколи у відкритому тексті), переживають перезапуск панелі та переживають сервери, до яких вони прив’язані (видалений сервер просто випадає з результатів цього токена).

Надішліть токен як облікові дані Bearer:

Authorization: Bearer msm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Немає файлів cookie та немає CORS: це для взаємодії сервер-сервер та викликів CLI, а не для браузерних програм з іншого джерела. Якщо панель знаходиться за зворотним проксі, переконайтеся, що проксі пересилає заголовок Authorization.

Помилки повертають 401 з { "ok": false, "error": "..." }. Будь-що, крім GET (або HEAD), повертає 405. Невідомі шляхи повертають 404. Коли API вимкнено, кожен маршрут повертає 404.

Кожен токен отримує власний бюджет, RATE_LIMIT_PUBLIC_API_PER_MIN (за замовчуванням 120 запитів/хвилину; 0 вимикає обмежувач). Перевищення ліміту повертає 429. Кожен запит, ще до перевірки його токена, також враховується в загальному ліміті на IP-адресу клієнта, що вп’ятеро перевищує це число, тому перевірка з відсутніми, неправильно сформованими, відкликаними або простроченими токенами не може обійти бюджет, обертаючи їх.

Кожен сервер, до якого прив’язаний токен.

{
"ok": true,
"total": 1,
"online": 1,
"servers": [
{
"id": "srv_ab12cd34",
"name": "SMP",
"type": "PAPER",
"state": "running",
"cpuPct": 18.4,
"memoryMb": 2048,
"memoryLimitMb": 4096,
"uptimeSeconds": 11722,
"players": { "online": 3, "max": 20 }
}
]
}

Один сервер, той самий об’єкт під ключем server. Повертає 404 для невідомого id та для сервера, до якого токен не прив’язаний (немає оракула існування), і 400 для неправильно сформованого id.

Поле Значення
total Скільки серверів видимі для цього токена (після фільтра його області видимості).
online Скільки з них у стані: running.
id Стабільний ідентифікатор сервера (srv_...).
name Відображувана назва.
type Тип сервера itzg (PAPER, FABRIC, AUTO_CURSEFORGE, …).
state running, starting, stopped або crashed: стабільний підсумок внутрішнього стану панелі.
cpuPct Недавній відсоток використання ЦП або null, коли сервер не працює.
memoryMb Резидентна пам’ять у МБ або null.
memoryLimitMb Налаштований ліміт пам’яті контейнера в МБ або null.
uptimeSeconds Секунди з моменту запуску контейнера або null.
players { online, max } або null, доки сервер не надасть список гравців.
Terminal window
curl -s https://panel.example.com/api/v1/servers \
-H "Authorization: Bearer $MSM_TOKEN" | jq