Ключи для внешних систем

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

Страница «Система» → «API-ключи» управляет доступом ботов, импортёров и скриптов к базе знаний. Программа передаёт ключ вместо входа по почте.

Сотрудникам ключи не нужны: они заходят по ссылке, которая приходит на адрес. Ключ — только для программ.

Список ключей

Заголовок — «API-ключи», под ним подпись «Управление ключами для внешних интеграций (боты, импортёры)». Справа вверху — кнопка «Создать ключ».

Столбцы: «Имя», «Префикс», «Папки», «Создан», «Последнее использование», «Статус», «Действия».

«Имя» — то, что вы написали при выпуске. Под ним мелким шрифтом стоят описание и адрес того, кто ключ выпустил.
«Префикс» — начало ключа с многоточием. Целиком ключ нигде больше не показывается, и префикс существует ровно для того, чтобы отличить один ключ от другого.
«Папки» — список папок базы знаний, к которым этот ключ допущен.
«Последнее использование» — когда ключом пользовались в последний раз. Прочерк значит «ни разу».
«Статус» — «Активен», «Истёк» (наступил срок, указанный при выпуске) или «Отозван».

Пока не выпущено ни одного ключа, вместо таблицы стоит «API-ключей ещё нет».

Как выпустить ключ

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

Нажмите «Создать ключ».

Заполните «Имя ключа» — по нему вы потом узнаете ключ в списке. Не длиннее ста символов.

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

Отметьте галочками папки в блоке «Папки библиотеки». Нужна хотя бы одна.

Если ключ временный, укажите «Срок действия». Под полем написано «Оставьте пустым для бессрочного ключа».

Нажмите «Создать ключ» внизу формы.

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

Нажмите «Готово», и новая строка появится в списке.

Форма не даст себя отправить с пустым именем («Введите имя ключа») или без единой отмеченной папки («Выберите хотя бы одну папку»).

Что ключ открывает

Ключ работает только с базой знаний и только с теми папками, которые вы отметили. Обращение к любой другой папке портал отклоняет.

Что можно сделать ключом:

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

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

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

Изменение и отзыв

Кнопка «Редактировать» открывает окно «Редактировать API-ключ»: там меняются имя, описание и набор папок. Срока действия в этом окне нет — если ключ выпущен бессрочным, бессрочным он и останется.

Кнопка «Отозвать» закрывает ключ навсегда. Портал переспросит: «Отозвать API-ключ "…"? Это действие нельзя отменить.» — и это не фигура речи.

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

Выпуск, изменение и отзыв ключа попадают в журнал действий.

Журнал вызовов

Журнал одного ключа: сводка сверху, ниже — каждое обращение с папкой, числом файлов и адресом

Кнопка «Логи» в строке ключа открывает страницу «Журнал использования API-ключа». Наверху стоят четыре счётчика по всем сохранённым обращениям: «Всего запросов», «Файлов загружено», «Объём данных», «Уникальных IP».

Ниже — таблица обращений: «Дата и время», «Действие», «Папка», «Файлы», «Размер», «IP-адрес», «Статус», «Время».

«Действие» подписано по-русски: «Загрузка файлов», «Список файлов», «Удаление файла», «Просмотр папки», «Переиндексация». Действия, для которых подписи нет, выводятся как есть, латиницей — это не ошибка.
«Папка» показывает название. Если папку с тех пор удалили, вместо названия стоит серый обрывок внутреннего кода с многоточием — наведите на него, и всплывёт подсказка «Папка удалена». Прочерк значит, что обращение вообще не относилось к папке.
«Статус» — числовой код ответа. Зелёный означает, что обращение прошло, жёлтый — что портал отказал (чаще всего папка не входит в список ключа), красный — сбой на стороне портала.
«Время» — сколько заняло обращение.

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

Пока обращений не было, стоит «Логов ещё нет». Записи старше девяноста дней портал удаляет сам.

Если что-то пошло не так

Внешняя система получает отказ, хотя ключ активен. Сверьте столбец «Папки»: ключ допущен только к перечисленным. Обращение к чужой папке видно в журнале жёлтой строкой.
В форме выпуска нет нужной папки. В списке показываются первые сто папок общей базы знаний. Папки, которые наполняются из Git, и личные библиотеки сотрудников сюда не попадают.
«Нет доступных папок». В общей базе знаний ещё не создано ни одной папки. Заведите её в разделе «База знаний».
«Последнее использование» пустое, хотя система работает. Значит, она ходит в портал не этим ключом. Сверьте «Префикс» с началом строки, которую ей выдали.
Ключ потерян. Восстановить нельзя. Выпустите новый, передайте его, затем отзовите старый.