API v2 управляет Kraken по HTTP и возвращает ответы в JSON. Доступен при активном лицензионном ключевом файле. Команды v1 работают в Community Edition и описаны на странице API.
Актуально для Kraken 2.23.0.
- Быстрый старт
- Базовый URL и авторизация
- Коды ответов
- Эндпоинты
- Настройки
- [PRO] GET /v2/settings
- [PRO] POST /v2/settings
- Маршруты
- [PRO] GET /v2/routes
- [PRO] POST /v2/routes
- [PRO] POST /v2/routes/{id}/start
- [PRO] POST /v2/routes/{id}/stop
- [PRO] DELETE /v2/routes/{id}
- Отправка и статистика
- [PRO] POST /v2/messages/start
- [PRO] POST /v2/messages/stop
- [PRO] GET /v2/statistics
- Шаблоны, плейбуки и профили
- [PRO] GET /v2/templates
- [PRO] POST /v2/templates
- [PRO] DELETE /v2/templates/{name}
- [PRO] GET /v2/playbooks
- [PRO] POST /v2/playbooks/{id}/run
- [PRO] GET /v2/profiles
- [PRO] POST /v2/profiles/{name}/select
- Мониторинг
- [PRO] GET /v2/monitoring
- [PRO] POST /v2/monitoring/start
- [PRO] POST /v2/monitoring/stop
- Ограничения
- Связанные разделы
Быстрый старт
- Включите API в Settings и задайте ключ в поле API Key.
- Скопируйте ключ.
- Проверьте доступ:
GET /v2/settingsс заголовкомX-API-KEY.
Базовый URL и авторизация
Базовый URL: http://127.0.0.1:6015. Порт по умолчанию - 6015, меняется в Settings.
Авторизация - только заголовок X-API-KEY. Ключ задается в Settings; в query-строке ключ не принимается.
curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/settings Формат запросов:
GET- параметры в query-строке, тело пустое;POST- тело в формате JSON (Content-Type: application/json);DELETE- тело пустое, объект указан в пути.
Все ответы, кроме ошибки авторизации и отказа без активного лицензионного ключевого файла, имеют Content-Type: application/json; charset=utf-8.
Коды ответов
200- запрос выполнен.201- объект создан или запущен.400- невалидный JSON или значение параметра.401- неверный или отсутствующий API-ключ. Тело ответа пустое.404- объект не найден или API v2 недоступен без активного лицензионного ключевого файла.405- метод не поддерживается; в ответе заголовокAllow.409- конфликт: объект уже существует или операция не завершилась.423- конфликт состояния: отправка или мониторинг уже запущены либо еще не запущены.429- превышен лимит запросов; в ответе заголовокRetry-After.500- внутренняя ошибка.502- API-ключ не задан в Settings; API не принимает запросы.
Ошибки возвращаются объектом с одним полем:
{"error":"not found"} Коды 401, 404 (без PRO), 405, 429, 500 и 502 относятся ко всем методам. Ниже для каждого метода показан пример успешного ответа и, где это полезно, пример ошибки.
Без активного лицензионного ключевого файла любой запрос к /v2/ получает 404 с текстом API v2 requires a PRO license. Здесь тело - обычный текст, а не JSON.
Эндпоинты
Настройки
[PRO] GET /v2/settings
Возвращает текущие настройки отправки.
Параметров нет.
curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/settings Пример ответа:
{
"flow_distribution": 0,
"flow_distribution_name": "Normal",
"eps": 9000,
"send_count": 1,
"message_threads": 3
} flow_distribution- распределение потока:0- Normal,1- Random,2- Duplicate.flow_distribution_name- название режима.eps- целевой EPS.send_count- количество потоков отправки.message_threads- количество потоков генерации.
[PRO] POST /v2/settings
Изменяет распределение потока и лимит EPS. Остальные поля не меняются. Возвращает настройки в том же виде, что и GET.
Тело запроса:
{
"flow_distribution": 2,
"eps": 5000
} Поля необязательны; передавайте только те, которые нужно изменить.
curl -X POST -H "X-API-KEY: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"flow_distribution":2,"eps":5000}' \
http://127.0.0.1:6015/v2/settings Пример ответа:
{
"flow_distribution": 2,
"flow_distribution_name": "Duplicate",
"eps": 5000,
"send_count": 1,
"message_threads": 3
} Ошибки:
400- невалидное значение:
{"error":"flow_distribution must be an integer in 0..2"} 400- отрицательный EPS:
{"error":"eps must be a non-negative integer"} 405- метод не поддерживается:
{"error":"method not allowed"} Маршруты
[PRO] GET /v2/routes
Возвращает список маршрутов.
curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/routes Пример ответа:
[
{
"id": "1",
"name": "Nginx",
"host": "10.0.0.10",
"port": "514",
"proto": "UDP",
"active": false
}
] [PRO] POST /v2/routes
Создает маршрут. Обязательные поля - name (имя шаблона), host, port. Поле proto необязательно, по умолчанию UDP.
Тело запроса:
{
"name": "Nginx",
"host": "10.0.0.10",
"port": 514,
"proto": "UDP"
} curl -X POST -H "X-API-KEY: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Nginx","host":"10.0.0.10","port":514}' \
http://127.0.0.1:6015/v2/routes Пример ответа 201:
{"id":"2"} Ошибки:
400- нет обязательного поля или невалидное значение:
{"error":"name is required"} 400- шаблон не найден:
{"error":"template not found: Custom"} 400- порт вне диапазона:
{"error":"port must be in the range 1..65535"} [PRO] POST /v2/routes/{id}/start
Запускает отправку сообщений по всем маршрутам. Указанный маршрут должен существовать; проверка не меняет поведение кнопки Start в Messages.
curl -X POST -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/routes/1/start Пример ответа:
{"status":"started"} Ошибки:
404- маршрут не найден:
{"error":"route not found"} 423- отправка уже идет:
{"error":"messages are already running"} 409- запуск не удался; в тексте ошибки причина от проверки маршрутов.
[PRO] POST /v2/routes/{id}/stop
Останавливает отправку сообщений.
curl -X POST -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/routes/1/stop Пример ответа:
{"status":"stopped"} Ошибки:
404- маршрут не найден.423- отправка не запущена:
{"error":"messages are not running"} [PRO] DELETE /v2/routes/{id}
Удаляет маршрут. Эквивалентная команда - POST /v2/routes/{id}/delete.
curl -X DELETE -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/routes/2 Пример ответа:
{"status":"deleted"} Ошибки:
404- маршрут не найден.500- маршрут не удален:
{"error":"route could not be deleted"} Отправка и статистика
[PRO] POST /v2/messages/start
Запускает отправку сообщений по всем маршрутам.
curl -X POST -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/messages/start Пример ответа:
{"status":"started"} Ошибки:
423- отправка уже идет:
{"error":"messages are already running"} 400- ошибка проверки маршрута или шаблона; текст ошибки содержит причину.409- запуск не удался по другой причине.
[PRO] POST /v2/messages/stop
Останавливает отправку сообщений.
curl -X POST -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/messages/stop Пример ответа:
{"status":"stopped"} Ошибка 423:
{"error":"messages are not running"} [PRO] GET /v2/statistics
Возвращает текущую статистику отправки.
curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/statistics Пример ответа:
{
"Messages": true,
"EPS": 15000,
"AVG": 14850,
"Sending": 1234567,
"Time": 42
} Messages- признак активной отправки.EPS- текущий EPS.AVG- средний EPS.Sending- количество отправленных событий.Time- время работы, секунд.
Шаблоны, плейбуки и профили
[PRO] GET /v2/templates
Возвращает список шаблонов из каталога etc.
curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/templates Пример ответа:
[
{
"name": "Nginx",
"author": "",
"version": 3,
"enable": true,
"index": "Test",
"type": "_doc"
}
] [PRO] POST /v2/templates
Создает шаблон. Обязательное поле - name. Остальные поля необязательны: author, index, type, enable, overwrite, json, post, templates, message.
Тело запроса:
{
"name": "Custom",
"index": "Test",
"type": "_doc",
"templates": ["custom event from {hostname}"]
} curl -X POST -H "X-API-KEY: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Custom","templates":["custom event"]}' \
http://127.0.0.1:6015/v2/templates Пример ответа 201:
{"name":"Custom","status":"created"} Ошибки:
400- невалидное имя:
{"error":"name is invalid"} 409- шаблон уже существует:
{"error":"template already exists: Custom"} [PRO] DELETE /v2/templates/{name}
Удаляет шаблон по имени.
curl -X DELETE -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/templates/Custom Пример ответа:
{"status":"deleted"} Ошибки:
404- шаблон не найден:
{"error":"template not found: Custom"} 500- шаблон не удален.
[PRO] GET /v2/playbooks
Возвращает список плейбуков.
curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/playbooks Пример ответа:
[
{
"id": "3f2a6c1e-9b7d-4c2a-8e5f-1a2b3c4d5e6f",
"name": "Base scenario"
}
] [PRO] POST /v2/playbooks/{id}/run
Запускает плейбук по идентификатору.
curl -X POST -H "X-API-KEY: $API_KEY" \
http://127.0.0.1:6015/v2/playbooks/3f2a6c1e-9b7d-4c2a-8e5f-1a2b3c4d5e6f/run Пример ответа 201:
{"status":"started"} Ошибка 404:
{"error":"playbook not found"} [PRO] GET /v2/profiles
Возвращает список профилей Messages.
curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/profiles Пример ответа:
[
{
"name": "Default"
}
] [PRO] POST /v2/profiles/{name}/select
Выбирает профиль Messages. Эквивалентная команда - POST /v2/profiles/{name}/apply.
curl -X POST -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/profiles/Default/select Пример ответа:
{"status":"selected"} Ошибки:
404- профиль не найден:
{"error":"profile not found: Default"} 423- отправка запущена, профиль менять нельзя:
{"error":"messages are running"} Мониторинг
[PRO] GET /v2/monitoring
Возвращает состояние мониторинга.
curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/monitoring Пример ответа:
{
"running": false,
"uptime": 0,
"samples": 0,
"host": "192.0.2.10",
"port": 22
} running- мониторинг запущен.uptime- время работы, секунд.samples- количество собранных измерений.host,port- узел мониторинга из Settings.
[PRO] POST /v2/monitoring/start
Запускает мониторинг и отвечает после смены состояния.
curl -X POST -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/monitoring/start Пример ответа:
{"status":"started"} Ошибки:
423- мониторинг уже запущен:
{"error":"monitoring is already running"} 423- предыдущий запуск или остановка еще выполняются:
{"error":"monitoring transition in progress"} 409- состояние не изменилось:
{"error":"monitoring did not start"} 500- ошибка запуска; текст содержит причину.
[PRO] POST /v2/monitoring/stop
Останавливает мониторинг и отвечает после смены состояния.
curl -X POST -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/monitoring/stop Пример ответа:
{"status":"stopped"} Ошибки:
423- мониторинг не запущен:
{"error":"monitoring is not running"} 423- переход уже выполняется:
{"error":"monitoring transition in progress"} 409- состояние не изменилось:
{"error":"monitoring did not stop"} 500- ошибка остановки; текст содержит причину.
Ограничения
- API не использует TLS: порт 6015 должен быть доступен только из доверенной сети.
- Лимит запросов - 600 за 60 секунд с одного IP; при превышении
429и заголовокRetry-After. - Для работы API v2 нужен активный лицензионный ключевой файл.