Документация1С-Битрикс: Модулиnative.apiНастройки модуля

Логирование

Вкладка «Логирование» находится в разделе «Сервисы → API-платформа → Настройки модуля». Здесь включаются журналы входящих и исходящих данных, выбираются события для аудита и места хранения записей.

Способы записи

Для событий модуля, токенов и безопасности используются два независимых флажка:

Событие
├─ Флажок события → системный журнал Битрикса
│  ├─ «События модуля» → все записанные события модуля
│  └─ «Журнал безопасности» → только отказы по ограничениям
│
└─ «Записывать в файл» → отдельный файл события

Можно включить один способ или оба. Если оба выключены, событие не записывается. Отключение записи не отменяет проверок доступа.

Для входящих и исходящих данных основная галочка сохраняет данные для просмотра в карточке запроса, а «Записывать в файл» — в файлах запроса. Эти данные не направляются в системный журнал событий.

Журналы в админке

«События модуля» и «Журнал безопасности» открывают один системный журнал с разными фильтрами. Для просмотра нужны права системного журнала Битрикса. Право чтения журналов в модуле управляет только ссылками в меню.

Данные запросов доступны в разделе «Входящие запросы» и его карточке. Для них действует право чтения входящих запросов.

Файловые журналы

Файлы сохраняются в каталоге, заданном в поле «Путь к логам». Там же описаны создание защитного .htaccess, сохранение существующих правил и настройка Nginx. События сохраняются в native.api/YYYY-MM-DD/EVENT_CODE.log, где EVENT_CODE — код события. Данные запроса хранятся в отдельном каталоге:

native.api/REQUEST_RECEIVED/{REQUEST_ID}/
├─ request.json
└─ response.json или response.xml

request.json содержит дату, REQUEST_ID, путь URI, CONTENT_TYPE, заголовки HEADER и параметры DATA. Файл ответа содержит только итоговое тело после маскирования, без заголовков, служебных полей и дополнительной обёртки. Заголовки ответа сохраняются в базе.

Для XML-ответа создаётся response.xml, для JSON — response.json. При неизвестном формате используется response.json с замаскированным непустым содержимым; расширение в этом случае не означает, что внутри корректный JSON. Для HEAD и ответов без тела файл ответа пустой. Каждый файл создаётся только при включённом направлении записи.

В файловых записях модуль маскирует распознанные пароли, токены и другие секреты. К записям в системном журнале событий такая дополнительная обработка не применяется. Учитывайте это при выборе способа записи, особенно для данных пользовательских обработчиков.

Входящие запросы

На вкладке «Аналитика» включите «Собирать входящие запросы» и сохраните настройки.
В группе «Входящие запросы» вкладки «Логирование» выберите данные и места хранения.
Выполните новый API-запрос и откройте его карточку либо каталог файлов по REQUEST_ID.

Параметр	Основная галочка	«Записывать в файл»
Записывать входящие данные	Параметры и заголовки в базе	`request.json` с параметрами и заголовками
Записывать исходящие данные	Тело и заголовки ответа в базе	Только тело в `response.json` или `response.xml`

Все четыре флажка независимы и по умолчанию выключены. Сбор запросов включается отдельно.

Собирать входящие запросы?
├─ Да → сохранять все обращения к обработчику API
│  ├─ Входящие данные → включённые направления: база / файл
│  └─ Исходящие данные → включённые направления: база / файл
└─ Нет
   ├─ Действует лимит → только основная запись запроса
   └─ Лимита нет → запись истории не создаётся

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

Маскирование данных

Перед записью входящих и исходящих данных в базу и файлы маскируются распознаваемые логины, пароли, токены, ключи, Authorization и Cookie, включая вложенные JSON-значения и XML-элементы и атрибуты. Маска — ******. Если содержимое ответа невозможно безопасно обработать, оно целиком заменяется маской.

URI хранит путь без GET-параметров и не проходит строковое маскирование. Параметры URL сохраняются отдельно в QUERY, где чувствительные значения маскируются. Не передавайте секреты в сегментах пути. Маскирование не гарантирует распознавание секрета под произвольным именем и не заменяет ограничение доступа к журналам.

Это правило относится к журналам данных запросов и файловому аудиту. Системный журнал событий получает данные без дополнительного маскирования модулем.

События модуля

Параметр	Что фиксируется
Записывать обновление настроек модуля	Изменения сохранённых настроек
Записывать ошибки запуска модуля	Ошибки при запуске API
Записывать очистку кеша модуля	Очистка через кнопку «Очистить кеш»

Аудит обработчиков

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

Включайте запись при разработке и разборе ошибок. Она может содержать большой объём данных запроса; после диагностики отключите её, если постоянный сбор не нужен.

События токенов

Параметр	Что фиксируется
Записывать создание токена	Добавление записи токена
Записывать изменение токена	Изменённые значения записи до и после обновления
Записывать удаление токенов клиента	Удаление токенов при отзыве клиента через API
Записывать смену ключа шифрования	Генерация нового ключа в настройках безопасности

Операции с токенами описываются в разделе «Токены авторизации», а срок действия и смена ключа — на вкладке «Безопасность».

События безопасности

Для каждого ограничения можно включить отдельную запись отказов.

Параметр	Причина отказа
Записывать отказы по Blacklist групп	Группа пользователя входит в запрещённый список роута
Записывать отказы по Whitelist групп	У пользователя нет группы из разрешённого списка роута
Записывать отказы по Blacklist IP-адресов	IP-адрес входит в запрещённый список
Записывать отказы по Whitelist IP-адресов	IP-адрес отсутствует в разрешённом списке
Записывать отказы по режиму работы запросов	Запрос поступил вне разрешённого времени
Записывать превышение лимита запросов	Исчерпано допустимое количество запросов
Записывать отказы CORS	Источник или запрошенные заголовки не разрешены настройками CORS

Режим работы, лимиты, глобальные IP-списки и CORS задаются на вкладке «Безопасность». Ограничения по группам и IP-списки роута задаются в его карте. Параметры журналирования отказов по IP действуют на оба уровня проверки.

Передача данных вендору

Параметр предназначен для записи событий передачи технических данных разработчику. Сейчас сбор и отправка этих данных не выполняются, поэтому такие записи не создаются. Включение журналирования само по себе не разрешает передачу данных.

Разрешение задаётся отдельно на вкладке «Основные».