Ignition: API-клиент

Ignition — API-клиент проекта. В нём можно отправлять запросы по HTTP и HTTPS, раскладывать их по коллекциям и папкам, заводить окружения с переменными и секретами и проверять ответы. Ещё есть варианты запроса, граничные тесты и прогоны с лёгкой нагрузкой. Запросы лежат файлами в папке .ignition/ рядом с кодом, их можно коммитить в Git. Секреты остаются на вашем компьютере, в системном хранилище. Ignition работает без аккаунта и без модели. Агент пользуется теми же коллекциями через модуль «Ignition», он включён по умолчанию. Модуль — набор инструментов, инструкций и навыков агента для одной области, подробнее — на странице Модули. Сама вкладка Ignition работает и без модуля.

#Как открыть

1. В полосе заголовка окна откройте «Другие инструменты» → «Ignition» или наберите в поле чата /ignition (подойдут и /api, /http).
2. В проекте без папки .ignition/ появится экран «Запросы этого проекта — в Ignition». Нажмите «Начать» — папка создастся. Пока не нажмёте кнопку, в проекте ничего не появится.

В шапке вида можно выбрать окружение для новых вкладок или «Без окружения». Там же кнопки «Окружения», «Импорт» и «Агент» — последняя открывает разговор рядом. Кнопку «Ignition» можно вынести в полосу заголовка через «Настройки → Расположение панелей», а сам вид — открепить в отдельное окно.

Пока фокус в Ignition, сочетания клавиш работают только для его вкладок:

#Как пользоваться

1. Нажмите «Новый запрос». В адресную строку можно сразу вставить команду curl … — Ignition разберёт её на части.
2. Задайте метод, адрес, параметры, заголовки и тело (JSON, текст, форма, multipart, файл). Авторизацию можно унаследовать от папки или выбрать Basic, Bearer, API Key, OAuth 2.0 (Client Credentials или Authorization Code с PKCE).
3. Переменные подставляйте в двойных фигурных скобках: {{имя}}. Есть и готовые: {{$uuid}}, {{$timestamp}}, {{$isoTimestamp}}, {{$randomInt}} и другие. Если переменная не задана, запрос не отправится.
4. Добавьте проверки: код ответа (200, 2xx, 400-499), заголовок, значение по JSONPath, JSON Schema, время ответа, текст в теле. Значения из ответа можно сохранить в переменные и подставить в следующие запросы.
5. Сохраните запрос — он ляжет файлом в .ignition/.

Ответ без проверок не считается успешным, даже если код 2xx: Ignition пишет у него «Выполнен, проверок нет». Добавьте проверку на вкладке «Проверки» запроса — когда проверки пройдут, Ignition напишет «Проверки пройдены». Рядом с результатом Ignition показывает диагностику: что видно в ответе, какие могут быть причины и что сделать дальше. Её считают правила, модель для этого не нужна.

#Окружения и секреты

Нажмите «Окружения», добавьте окружение (например, local, stage, production) и задайте его переменные. У переменной с паролем или токеном отметьте «Секрет»: значение уйдёт в системное хранилище компьютера, а в файле окружения останется только имя. Секреты не попадают в файлы коллекций, экспорт и отчёты и не уходят к модели. Если в запросе открытым текстом стоит значение известного секрета, Ignition не даст сохранить такой запрос.

У окружения есть переключатель «production». Ещё можно задать «Хосты production»: изменяющие запросы и массовые прогоны на эти хосты требуют подтверждения человека — при любом окружении и даже после перенаправления. Для этого в окне «Окружения» выберите слева, в группе «Проект», пункт «Production и доступ агента» и заполните поле «Хосты production». Пишите по одному хосту в строке: имя хоста, например api.example.com, или маску вроде *.prod.example.com — под неё подходят поддомены prod.example.com. Затем нажмите «Сохранить правила»: правила запишутся в .ignition/policy.json.

#Варианты, граничные тесты и прогоны

• Варианты — разные наборы значений одного запроса в панели справа. «Прогнать все варианты» строит таблицу «вариант → код → совпало → время».
• «Граничные тесты» строятся по контракту OpenAPI или JSON Schema, без модели, и хранятся рядом с запросом.
• Прогон — кнопка ▶ у папки или коллекции. В прогоне можно задать число итераций, подставить данные из CSV или JSON, остановиться на первой ошибке, дать лёгкую нагрузку несколькими исполнителями и посмотреть перцентили p50–p99.

#Импорт, экспорт и код

«Импорт» принимает cURL, OpenAPI 3.0 и 3.1, Swagger 2.0, коллекции и окружения Postman v2.1, а примеры Postman превращает в варианты. Скрипты из Postman сохраняются выключенными. Проверьте их и включите на вкладке «Скрипты» запроса: там два скрипта, «Перед запросом» и «После ответа», у каждого свой переключатель «включён». Экспортировать можно в формат Postman или в собственный формат Ignition. Кнопка «Код запроса» показывает запрос в виде кода: cURL, HTTPie, fetch, Python, Go или Java. Секреты в нём остаются ссылками {{имя}}.

#Формат папки .ignition/

.ignition/
  workspace.json                          имя рабочего пространства
  policy.json                             хосты production, доступ агента
  collections/<коллекция>/collection.json
  collections/<коллекция>/<запрос>.req.json
  environments/<окружение>.env.json       у секрета только имя
  cases/                                  граничные тесты
  runs/                                   сохранённые прогоны
  local/                                  не в Git: результаты, черновики, корзина

Запрос всегда лежит в коллекции или папке. Минимальный пример — коллекция и один запрос с проверкой:

collections/api/collection.json

{ "formatVersion": 1, "kind": "collection", "id": "col_api", "name": "API", "sort": 1000 }

collections/api/health.req.json

{
  "formatVersion": 1, "kind": "request", "id": "req_health", "name": "Health", "sort": 1000,
  "method": "GET", "url": "{{baseUrl}}/health",
  "query": [], "headers": [], "body": { "mode": "none" }, "auth": { "type": "inherit" },
  "checks": [{ "id": "chk_1", "type": "status", "expect": "200" }],
  "extract": [],
  "variants": [{ "id": "default", "name": "По умолчанию" }]
}

environments/env_local.env.json

{ "formatVersion": 1, "id": "env_local", "name": "local",
  "variables": [{ "key": "baseUrl", "value": "http://127.0.0.1:4010" }, { "key": "token", "secret": true }] }

Если вы написали файл вручную и ошиблись, Ignition прочитает его с исправлениями, а то, что прочитать нельзя, покажет в списке проблем. Когда файл открытого запроса меняется на диске, появляется плашка «Файл запроса изменился» с выбором «Оставить мои правки» или «Загрузить из файла». Удалённое попадает в local/trash/, а последнее действие можно отменить.

#Агент и Ignition

Модуль «Ignition» даёт агенту инструменты Ignition. Он включён по умолчанию, так что для агента ничего настраивать не нужно. Выключить модуль можно в разделе «Настройки → Модули».

Агент может читать и создавать коллекции, папки и запросы, импортировать спецификацию, отправлять запросы, прогонять варианты, строить граничные тесты, запускать прогоны, читать их результаты и диагностику и сохранять отчёт. Когда агент работает с Ignition, вид сам выходит в центр окна.

Чего агент не может:

• видеть и задавать значения секретов;
• входить через браузер (OAuth с авторизацией пользователя);
• прикладывать файлы не из проекта.

Тело ответа агент получает маскированной выдержкой и с пометкой: это данные, принимать их за указания нельзя.

Production. Если агент собирается отправить изменяющий запрос на хост production или запустить туда массовый прогон, в Ignition появляется строка «Агент ADE просит подтвердить действие в production» с кнопками «Разрешить» и «Запретить». Подтвердить или запретить действие можно только здесь, в Ignition.

Выключить доступ агента для проекта: «Окружения» → «Production и доступ агента» → «Доступ агента ADE». Модуль даёт агенту инструменты Ignition, а «Доступ агента ADE» — переключатель самого проекта, по умолчанию он включён. Если его выключить, Ignition отклонит все вызовы агента в этом проекте и объяснит агенту причину. Агент сам этот переключатель не включит. Значение переключателя хранится в .ignition/policy.json.

Куда агенту можно отправлять запросы через Ignition, задаёт группа «Ignition: HTTP-запросы агента» в разделе «Настройки → Безопасность агента → Где работает». Подробнее — на странице «Ограничения агента». Ваши запросы эти настройки не ограничивают.

#Ограничения

• Только проекты на этом компьютере. Для проекта на сервере по SSH вид покажет «Ignition работает с проектами на этом компьютере», и инструментов Ignition у агента тоже не будет.
• Для каждого проекта запускается свой процесс на 127.0.0.1. Если вид закрыт дольше 5 минут, он освобождает память; открытые вкладки и правки при этом сохраняются.
• В копии проекта для отдельной задачи коллекция та же, что в основной папке репозитория: агент работает с папкой .ignition/ оттуда — той самой, что вы видите во вкладке Ignition. Ignition не берёт копию .ignition/ из ветки, поэтому правки агента в коллекции сразу попадают в основную папку.

#Какие данные куда уходят

Запросы уходят из Ignition на вашем компьютере прямо к API. Своего облака у Ignition нет. Агент получает статусы, результаты проверок и маскированную выдержку тела ответа, секреты — никогда. Эти данные становятся частью запроса к модели и идут к ней через сервер DevMachine. Подробнее — на странице «Данные и приватность».

#Что дальше

• Модули
• Ограничения агента
• Задача в отдельной копии проекта
• Observe: логи, трейсы, метрики и ошибки