Kibana Dev Tools и работа через REST API

Когда Kibana подключена к кластеру — а как именно это происходит через enrollment-токен, мы разобрали в статье Безопасность по умолчанию в Elasticsearch 8 — Dev Tools Console становится главным рабочим инструментом. Она подсвечивает синтаксис Query DSL, автодополняет пути и параметры, сама проставляет заголовки авторизации. На этапе обучения это экономит немало времени.

Но понимать структуру запроса всё равно важно: то, что консоль делает за вас, нужно уметь воспроизвести руками в curl или любом HTTP-клиенте.

Где найти Dev Tools

В левом боковом меню Kibana перейдите в Management → Dev Tools (иконка </>) или откройте /app/dev_tools#/console напрямую в браузере. Откроется редактор с двумя панелями: слева — запрос, справа — ответ от Elasticsearch.

Интерфейс Kibana Dev Tools Console: слева редактор запроса, справа панель ответа от Elasticsearch.Source: https://www.elastic.co/kibana

Структура REST-запроса

Любое обращение к ES — это обычный HTTP-запрос. В Dev Tools он записывается так:

МЕТОД /путь
{
  "тело": "в JSON"
}

Метод определяет, что делаем:

  • GET — читаем: документ, настройки индекса, статус кластера;
  • POST — выполняем действие или создаём ресурс там, где ID генерируется автоматически;
  • PUT — создаём или полностью заменяем ресурс по конкретному пути;
  • DELETE — удаляем.

Путь — адрес ресурса, всегда начинается со /:

  • / — корневой эндпоинт, информация о кластере;
  • /_cat/indices?v — список индексов в читаемом виде;
  • /my-index — операции с индексом;
  • /my-index/_doc/1 — документ с ID 1;
  • /my-index/_search — поиск по индексу.

Тело — JSON-объект, пишется сразу под строкой метода без разделителей. Не у всех запросов оно нужно: GET / тела не требует, а POST /_search — требует.

sequenceDiagram participant U as Вы (браузер) participant K as Kibana Dev Tools participant E as Elasticsearch :9200 U->>K: МЕТОД /путь { тело } Note over K: Добавляет HTTPS и заголовки авторизации K->>E: HTTPS + Authorization + Content-Type E->>K: 200 OK + JSON-ответ K->>U: Подсвеченный результат
sequenceDiagram
    participant U as Вы (браузер)
    participant K as Kibana Dev Tools
    participant E as Elasticsearch :9200
    U->>K: МЕТОД /путь { тело }
    Note over K: Добавляет HTTPS и заголовки авторизации
    K->>E: HTTPS + Authorization + Content-Type
    E->>K: 200 OK + JSON-ответ
    K->>U: Подсвеченный результат
Как Dev Tools Console передаёт запрос к Elasticsearch
Check yourself
Вы хотите найти все документы в индексе `products`, где цена ниже 10 000. Какой HTTP-метод и путь вы напишете в Dev Tools? Нужно ли тело запроса?

Первые запросы в консоли

Пройдём от простого к практике.

Проверить, отвечает ли кластер:

GET /

В ответе — версия ES, имя кластера и "You Know, for Search". Если видите эту строку, соединение работает.

Список индексов:

GET /_cat/indices?v

Флаг ?v добавляет заголовок колонок. _cat-API специально возвращает текст, не JSON — удобно читать глазами. О других полезных _cat-командах читайте в статье Служебные API: _cat, здоровье кластера и настройки.

Создать индекс:

PUT /products
{
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 0
  }
}

Добавить документ с явным ID:

PUT /products/_doc/1
{
  "name": "Ноутбук",
  "price": 85000,
  "in_stock": true
}

Добавить документ — пусть ES сам придумает ID:

POST /products/_doc
{
  "name": "Мышь беспроводная",
  "price": 1500,
  "in_stock": true
}

Тонкость: PUT с путём _doc/ID требует явный ID; POST без ID генерирует его автоматически в виде длинной Base64-строки. Если ID важен для бизнес-логики — артикул, slug — используйте PUT. Если нет — POST.

Прочитать документ по ID:

GET /products/_doc/1

Простой поиск:

GET /products/_search
{
  "query": {
    "match": {
      "name": "ноутбук"
    }
  }
}
Check yourself
Вы запускаете `POST /products/_doc` и видите в ответе `"_id": "xK2mAZABpLk8Y3fRv1a-"`. Почему ID выглядит как длинная строка, а не как число или артикул?

Горячие клавиши и удобства консоли

  • Ctrl+Enter / Cmd+Enter — выполнить запрос, где стоит курсор;
  • Ctrl+I / Cmd+I — автоформатировать (выровнять отступы) текущий запрос;
  • Ctrl+/ / Cmd+/ — открыть документацию по текущему эндпоинту прямо в консоли;
  • несколько запросов можно держать на одном экране — консоль сама разберёт, где заканчивается один и начинается другой;
  • автодополнение работает как для путей (GET /_), так и для полей тела запроса;
  • консоль хранит историю последних 500 запросов — удобно вернуться к чему-то, что делали раньше.

Те же запросы через curl

Всё, что Dev Tools делает за вас, в curl нужно указать явно: HTTPS, авторизацию и заголовок Content-Type.

Базовый шаблон:

curl -X МЕТОД \
     -u elastic:ВАШ_ПАРОЛЬ \
     --cacert /etc/elasticsearch/certs/http_ca.crt \
     -H "Content-Type: application/json" \
     -d '{ "тело": "запроса" }' \
     https://localhost:9200/ПУТЬ

Что каждый флаг делает:

  • -X PUT — HTTP-метод; для GET можно не писать, это значение по умолчанию;
  • -u elastic:password — Basic-аутентификация;
  • --cacert — CA-сертификат для проверки TLS; для локальных экспериментов замените на -k (--insecure);
  • -H "Content-Type: application/json" — обязателен при отправке тела; без него ES вернёт 400 Bad Request;
  • -d '...' — тело запроса; одинарные кавычки снаружи позволяют без проблем использовать двойные внутри.

Практические примеры:

# Проверить кластер
curl -k -u elastic:M0nPass_w0rd https://localhost:9200

# Создать индекс
curl -k -u elastic:M0nPass_w0rd -X PUT \
  -H "Content-Type: application/json" \
  -d '{"settings":{"number_of_shards":1,"number_of_replicas":0}}' \
  https://localhost:9200/products

# Добавить документ
curl -k -u elastic:M0nPass_w0rd -X PUT \
  -H "Content-Type: application/json" \
  -d '{"name":"Ноутбук","price":85000,"in_stock":true}' \
  https://localhost:9200/products/_doc/1

# Поиск
curl -k -u elastic:M0nPass_w0rd -X GET \
  -H "Content-Type: application/json" \
  -d '{"query":{"match":{"name":"ноутбук"}}}' \
  https://localhost:9200/products/_search
Check yourself
В примерах curl используется флаг `-k`. Что он делает? Почему его нельзя использовать в продакшне?

Авторизация через API-ключ

Для скриптов и автоматизации лучше не хранить пароль суперпользователя elastic в коде. Создайте API-ключ:

POST /_security/api_key
{
  "name": "my-curl-key"
}

ES вернёт id и api_key. Из них формируется Base64-строка для заголовка:

# Закодировать строку id:api_key
echo -n "ВАШ_ID:ВАШ_API_KEY" | base64

# Использовать в запросе
curl -k -H "Authorization: ApiKey ПОЛУЧЕННАЯ_СТРОКА_BASE64" \
  https://localhost:9200

В Dev Tools вы с этим почти не столкнётесь — Kibana авторизуется сама. API-ключи нужны именно для внешних клиентов и CI-скриптов. Подробнее о правах и жизненном цикле ключей — в статье Безопасность: пользователи, роли и API-ключи.

Quick recall
Что будет, если в curl запросе забыть `-H "Content-Type: application/json"` при отправке тела?
Quick recall
Из чего состоит REST-запрос к ES в Dev Tools?
Quick recall
Когда добавляете документ в Elasticsearch — когда использовать `PUT /products/_doc/1`, а когда `POST /products/_doc`?

См. также

Sources

  1. Kibana Dev Tools Console | Kibana Guide
  2. Elasticsearch REST APIs | Elasticsearch Reference