Обзор API
Когда применять
Когда нужна программная интеграция с кластером: автоматизация операций, собственные инструменты, интеграция со смежными системами.
Методы
API vStack Center — это JSON-RPC 2.0 поверх HTTP. Запрос отправляется на HTTPS-endpoint кластера, ответ приходит синхронно либо в виде идентификатора асинхронной операции с последующим опросом состояния.
Конверт запроса и ответа
Запрос это обычный JSON-RPC 2.0: jsonrpc, method, params, id. Токен
сессии передаётся внутри params полем auth.cookie; на сервере cookie
заменяется на uid вызывающего. Подробности входа и принудительной смены пароля
описаны в «Аутентификации».
{"jsonrpc": "2.0", "method": "cluster-overview", "params": {"auth": {"cookie": "..."}}, "id": 1}
Ответ несёт два уровня исхода, и их важно не путать.
| Уровень | Где | Что означает |
|---|---|---|
| Транспортный | error.code, error.message | запрос не дошёл до предметной логики: нет сессии, нет прав, не разобрались параметры |
| Прикладной | result.code, result.data | метод выполнился; 1 это успех, 2 у входа означает «нужно сменить пароль» |
{"jsonrpc": "2.0", "id": 1, "result": {"code": 1, "data": {}}}
Коды отказов
Числовые коды отрицательные и разложены по доменам: свои ряды у ВМ, ВЦОД, сетей, Edge, хранилища, узлов, пользователей и журнала безопасности. Полные таблицы лежат на страницах соответствующих подсистем, здесь только сквозные правила.
| Код | Когда приходит |
|---|---|
-403 «Access denied» | не хватает прав. Авторизация выполняется до хендлера, поэтому пометодных кодов отказа по правам у большинства методов нет |
-1000 | идентификатор запроса уже занят, а сохранённый ответ отдать нельзя. Приходит только синхронному вызову. Повторите с новым id |
-9494 «No session token» | в params не передан auth.cookie |
-32602 | диспетчер не разобрал params метода или они не прошли проверку. Приходит на любом методе |
-12, -22 | коды ответа агента узла, а не ошибки API |
Идентификатор запроса стоит делать уникальным: по нему диспетчер отличает повтор от нового вызова. Повтор в работу не идёт — операция не выполняется второй раз, и на узел ничего не уходит. Что получит клиент, зависит от того, чей это повтор и закончилась ли первая попытка:
| Условие | Что приходит |
|---|---|
| тот же пользователь, тот же метод, ответ на первую попытку уже сохранён | тот же ответ дословно |
первая попытка ещё выполняется; либо id занят другим пользователем или другим методом | -1000 — повторяйте с новым id |
| клиент асинхронный | ничего: он ждёт результат первой попытки своим путём |
Проверка на владельца и метод — граница авторизации, а не удобство:
идентификатор задаёт клиент, и без этой проверки угаданный id выдал бы чужой
ответ в обход прав. Отдельный случай: синхронный клиент асинхронного метода может
получить -1000, а следом — настоящий ответ, когда операция закончится. Отдавать
ему на повтор нечего, пока она в работе, а молчать нельзя — вызов заблокирован.
Синхронные и асинхронные методы
Часть методов отвечает сразу из базы. Часть отдаёт задание агентам узлов, и тогда ответ приходит после завершения полного цикла, а не после его старта. У таких операций результат один раз в конце: прогресс диспетчер не отдаёт. Отдельные методы возвращают идентификатор операции, состояние которой читают своим методом статуса.
Практическое следствие: после записи узловых параметров читайте их обратно, а не считайте подтверждение интерфейса доказательством применения.
Что где искать
В 3.1.0 роутер принимает 206 методов. Ниже они сгруппированы по префиксу имени, чтобы было понятно, в какой раздел идти за описанием.
| Префикс | Методов | Раздел с описанием |
|---|---|---|
vm-, vms- | 44 | Виртуальные машины, Методы управления ВМ |
user-, role-, privilege- | 30 | Пользователи и доступ, Роли и привилегии |
vdc- | 20 | ВЦОД, Хранилище ВЦОД |
edge- | 17 | Edge-маршрутизаторы |
iscsi- | 15 | Группы инициаторов и порталов |
security- | 15 | Журнал безопасности |
cluster-, get-statusmap | 11 | Кластер, узлы и сервисы |
node-, host-, portgroup- | 12 | Управление узлами |
pd- | 10 | Замена диска |
net-, nets- | 9 | Сети |
backup- | 5 | Резервное копирование |
os-, golden- | 7 | Библиотека образов ОС |
pool-, pools-, filesystems-, snapshot- | 7 | Пулы хранения |
auth- | 3 | Аутентификация |
task- | 1 | Инвентарь и наблюдение |
Единственный метод, который обходит проверку прав, это auth-logout: он
оперирует только сессией самого вызывающего.
См. также
- Аутентификация — вход, токен сессии, принудительная смена пароля.
- Роли и привилегии — реестр привилегий и области действия.
- Методы управления ВМ — разбор методов переноса.