API Ботов
В SimpleOne API ботов позволяет интегрировать экземпляр со сторонними сервисами (такими как мессенджеры, системы ИИ и так далее) для решения различных бизнес-задач в зависимости от запроса. Например, при создании инцидента ответственная группа получает ув едомление в определенном мессенджере с указанной темой.
Для интеграции со сторонним сервисом выполните следующие шаги:
- Обеспечьте подготовку на другой стороне (зарегистрируйтесь, если необходимо, получите токен авторизации, проверьте документацию по API).
- Создайте запись типа бота.
- Настройте методы REST, используемые для взаимодействия со сторонним сервисом.
- Настройте экземпляр бота.
- Настройте параметры маршрутизации.
- Настройте правила маршрутизации.
Создание типа бота
Тип бота — это связующий элемент для методов и экземпляров бота. При создании вы можете указать, какие боты могут использовать настроенные методы, и наоборот.
Чтобы создать новый тип бота, выполните следующие действия:
- Перейдите в API ботов → Типы ботов.
- Нажмите Создать и укажите в поле Наименование название типа бота.
- Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.
Настройка REST методов бота
Настройте методы REST API, предоставляемые сторонней системой, для взаимодействия с ней. Методы бота привязаны к правилам маршрутизации и параметрам маршрутизации.
Чтобы создать и настроить новый метод бота, выполните следующие действия:
- Перейдите в API ботов → Методы ботов.
- Нажмите Создать и заполните поля.
- Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.
Поля формы Метод бота
Поле | Обязательно | Описание |
---|---|---|
Наименование | Да | Укажите название метода. |
URL-суффикс | Нет | Укажите относительный путь в дополнение к URL-адресу запроса. Полный URL-адрес запроса объединяется из постоянной части, указанной в поле URL-адреса экземпляра бота, и этого суффикса URL-адре са. |
Метод запроса | Да | Укажите способ запроса. Доступные опции:
|
Тип бота | Нет | Укажите тип бота, который может использовать этот метод. |
Параметр состояния | Нет | Определите параметр, который показывает, был запрос успешным или нет. Поле хранит строку, которую должно вернуть тело ответа, чтобы запрос считался успешным. Если поле не заполнено, запрос всегда будет считаться успешным (за исключением ошибок на экземпляре). |
Заголовки | Нет | При необходимости укажите заголовки методов. Допустимо использование переменных в угловых скобках. В примере ниже вместо переменной будет подставлен токен от экземпляра бота: authorization:Bearer <token>; Content-Type:application/json |
Содержимое | Нет | Укажите тело запроса. Разрешены переменные в угловых скобках. В следующем примере сообщение отправляется в канал обмена сообщениями, определ енный переменной <routing_parameter_0>, и маршрутизируется в поток в этом канале, заданный переменной <routing_parameter_1>. Содержимое этого сообщения определяется переменной <content>. Эти переменные должны быть определены в правиле маршрутизации бота. Нумерация параметров маршрутизации начинается с 0. |
{
"channel": "<routing_parameter_0>",
"text": "<content>",
"thread_ts": "<routing_parameter_1>",
}
Настройка экземпляра бота
Создайте экземпляр бота, чтобы продолжить настройку инте грации, используйте методы бота, правила маршрутизации.
Чтобы создать нового бота, выполните следующие действия:
- Перейдите в API ботов → Боты.
- Нажмите Создать и заполните поля.
- Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.
Поля формы Бот
Поле | Обязательно | Описание |
---|---|---|
Наименование | Да | Укажите название бота. |
Тип бота | Да | Укажите тип бота. Он включает в себя методы, которые может использовать этот бот. |
Токен | Нет | Укажите токен, если бот имеет авторизованный доступ к стороннему сервису. Этот токен должен быть предоставлен поставщиком API. |
URL | Да | Укажите URL-адрес для выполнения запросов. Эта часть URL является постоянной, в отличие от суффиксов URL, указанных для каждого метода бота. |
Настройка параметров маршрутизации
Параметры маршрутизации используются в правилах маршрутизации бота, чтобы сделать их более конкретными.
Основная цель этой функциональности – настройка корреляции между значением колонки при срабатывании правила маршрутизации бота и значением колонки, используемым в теле запроса.
Чтобы создать параметр маршрутизации, выполните следующие действия:
- Перейдите в API ботов → Параметры маршрутизации.
- Нажмите Создать и заполните поля.
- Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.
Поля формы Параметр маршрутизации
Поле | Обязательно | Описание |
---|---|---|
Метод бота | Да | Укажите метод, связанный с этим параметром маршрутизации. |
Значение колонки | Да | Укажите значение колонки для дополнительной маршрутизации. |
Parameter value | Нет | Укажите значение параметра, который будет подставлять вместо переменной <routing_parameter> в теле запроса запись со Значением колонки в определенном поле. Вы можете создать более одного параметра. Их следует нумеровать, начиная с 0:
|
Настройка правил маршрутизации бота
Таблица Правила маршрутизации ботов содержит условия и правила для срабатывания. при выполнении условий триггер выполняет запрос к внешней службе. Историю запросов можно найти в области связанных списков для каждой записи.
Чтобы создать правило маршрутизации, выполните следующие действия:
- Перейдите в API ботов → Правила маршрутизации ботов.
- Нажмите Создать и заполните поля.
- Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.
Поля формы Правило маршрутизации бота
- Общее
- Время запуска
- Содержимое
- Ответное действие
Поле | Обязательно | Описание |
---|---|---|
Наименование | Да | Укажите название правила маршрутизации. |
Бот | Да | Укажите бота, для которого необходимо настроить правило маршрутизации. |
Метод бота | Да | Укажите связанный метод бота. |
Бизнес-правило | Нет | Бизнес-правило генерируется автоматически, после сохранения записи правила. Оно основывается на параметры, заданные в связанных сущностях Бота и Метода бота. Это бизнес-правило вызывает системное событие, которое соответствует условиям правила. При обновлении правила маршрутизации, бизнес-правило обновляются автоматически. При удалении правила маршрутизации, бизнес-правило удаляется автоматически. |
Таблица | Да | Укажите таблицу, для которой будет работать правило маршрутизации. |
Активен | Нет | Установите флажок, чтобы активировать правило. |
Ответное действие | Нет | Установите этот флажок, если требуется обработка назначенного ответа REST. При установленном флажке появляется вкладка Ответное действие на форме. |
Направить по колонке | Нет | Укажите колонки, которые ссылаются на параметры маршрутизации. Если вам нужно сопоставить несколько параметров маршрутизации с соответствующими колонками, колонки в этом поле должны быть в том же порядке, что и параметры маршрутизации в тексте запроса. |
Поле | Обязательно | Описание |
---|---|---|
Добавление | Нет | Установите флажок, если правило маршрутизации должно выполнять действия при добавлении записи. |
Обновление | Нет | Установите флажок, если правило маршрутизации должно выполнять действия при обновлении записи. |
Удаление | Нет | Установите флажок, если правило маршрутизации должно выполнять действия при удалении записи. |
Порядок | Да | Укажите порядок правила маршрутизации. |
Условия запуска | Нет | Создайте условие для соответствия до выполнения правила маршрутизации. Используйте конструктор условий, чтобы задать необходимый фильтр. Вы можете использовать сложные фильтры с И и ИЛИ. Пустое условие всегда возвращает значение true. |
Поле | Обязательно | Описание |
---|---|---|
Расширенное содержимое | Нет | Установите флажок, если содержимое передаваемое в переменную <content> должно быть динамическим. Когда флажок установлен, появляется поле Скрипт содержимого. |
Скрипт содержимого | Нет | Укажите динамическое содержимое, передаваемое в переменную <content>. Введите свой скрипт и возвратите строковое значение содержимого с помощью директивы return. |
Содержимое | Нет | Укажите статическое содержимое (текст или инструкцию), передаваемое в переменную <content>. |
Поле | Обязательно | Описание |
---|---|---|
Параметр ответа | Да | Укажите путь до необходимого параметра содержимого ответа. Пример: ts.user.id |
Записать в таблицу | Да | Укажите таблицу, в которой будет записан параметр. |
Соотнесение (начальное) | Да | Укажите колонку таблицы, которая вызывает правило маршрутизации. Укажите значения в полях Соотнесение (начальное) и Соотнесение (искомое), если таблица ответов отличается от таблицы, которая вызывает запрос. |
Колонка для записи | Да | Укажите колонку, в которой будет записан параметр. |
Соотнесение (искомое) | Да | Укажите колонку таблицы, которая будет содержать р езультат запроса. Результат запроса фиксируется в запись таблицы, указанной в поле Записать в таблицу, у которой одинаковые значения в полях Соотнесение (начальное) и Соотнесение (искомое). Значение в поле Соотнесение (начальное) таблицы, указанной в поле Записать в таблицу, должно совпадать со значением в поле Соотнесение (искомое) таблицы, указанной в поле Записать в таблицу. Если значения не совпадают, возникает ошибка, которая записывается в Истории запросов ботов. |
История запросов ботов
Чтобы просмотреть историю обращений к сторонним сервисам, выполните следующие шаги:
- Перейдите в API ботов → История запросов ботов.
- Нажмите на запись, которую вам нужно просмотреть.
Поля формы История запросов бота
Поле | Описание |
---|---|
Запись | ID записи, из которой был сгенерирован запрос. |
Правило маршрутизации | Правило маршрутизации бота, по которому был сгенерирован запрос. |
Статус | Статус запроса. Доступные опции:
|
URL | Адрес указанного запроса. |
Метод | Метод указанного запроса. |
Заголовки | Заголовки указанного запроса. |
Содержимое | Содержимое указанного запроса. |
Ответ | Ответ запроса. Он полезен для отладки и устранения неполадок. В нем можно найти ошибки, возвращенные REST API стороннего сервиса, и ошибки, возникшие на стороне сервера, при создании или отправке запроса. |