Перейти к основному содержимому
Версия: 1.20.1

API Ботов

В SimpleOne API ботов позволяет интегрировать экземпляр со сторонними сервисами (такими как мессенджеры, системы ИИ и так далее) для решения различных бизнес-задач в зависимости от запроса. Например, при создании инцидента ответственная группа получает уведомление в определенном мессенджере с указанной темой.

Для интеграции со сторонним сервисом выполните следующие шаги:

  1. Обеспечьте подготовку на другой стороне (зарегистрируйтесь, если необходимо, получите токен авторизации, проверьте документацию по API).
  2. Создайте запись типа бота.
  3. Настройте методы REST, используемые для взаимодействия со сторонним сервисом.
  4. Настройте экземпляр бота.
  5. Настройте параметры маршрутизации.
  6. Настройте правила маршрутизации.

Создание типа бота​

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

Чтобы создать новый тип бота, выполните следующие действия:

  1. Перейдите в API ботов → Типы ботов.
  2. Нажмите Создать и укажите в поле Наименование название типа бота.
  3. Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.

Настройка REST методов бота​

Настройте методы REST API, предоставляемые сторонней системой, для взаимодействия с ней. Методы бота привязаны к правилам маршрутизации и параметрам маршрутизации.

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

  1. Перейдите в API ботов → Методы ботов.
  2. Нажмите Создать и заполните поля.
  3. Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.

Поля формы Метод бота

ПолеОбязательноОписание
НаименованиеДаУкажите название метода.
URL-суффиксНетУкажите относительный путь в дополнение к URL-адресу запроса. Полный URL-адрес запроса объединяется из постоянной части, указанной в поле URL-адреса экземпляра бота, и этого суффикса URL-адреса.
Метод запросаДаУкажите способ запроса. Доступные опции:
  • GET
  • POST
 Чтобы добавить больше методов, настройте опции выбора для этого поля.
Тип ботаНетУкажите тип бота, который может использовать этот метод.
Параметр состоянияНетОпределите параметр, который показывает, был запрос успешным или нет. Поле хранит строку, которую должно вернуть тело ответа, чтобы запрос считался успешным. Если поле не заполнено, запрос всегда будет считаться успешным (за исключением ошибок на экземпляре).
ЗаголовкиНетПри необходимости укажите заголовки методов. Допустимо использование переменных в угловых скобках.
В примере ниже вместо переменной будет подставлен токен от экземпляра бота: 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>",
}

Настройка экземпляра бота​

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

Чтобы создать нового бота, выполните следующие действия:

  1. Перейдите в API ботов → Боты.
  2. Нажмите Создать и заполните поля.
  3. Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.

Поля формы Бот

ПолеОбязательноОписание
НаименованиеДаУкажите название бота.
Тип ботаДаУкажите тип бота. Он включает в себя методы, которые может использовать этот бот.
ТокенНетУкажите токен, если бот имеет авторизованный доступ к стороннему сервису. Этот токен должен быть предоставлен поставщиком API.
URLДаУкажите URL-адрес для выполнения запросов. Эта часть URL является постоянной, в отличие от суффиксов URL, указанных для каждого метода бота.

Настройка параметров маршрутизации​

Параметры маршрутизации используются в правилах маршрутизации бота, чтобы сделать их более конкретными.

Основная цель этой функциональности – настройка корреляции между значением колонки при срабатывании правила маршрутизации бота и значением колонки, используемым в теле запроса.

Чтобы создать параметр маршрутизации, выполните следующие действия:

  1. Перейдите в API ботов → Параметры маршрутизации.
  2. Нажмите Создать и заполните поля.
  3. Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.

Поля формы Параметр маршрутизации

ПолеОбязательноОписание
Метод ботаДаУкажите метод, связанный с этим параметром маршрутизации.
Значение колонкиДаУкажите значение колонки для дополнительной маршрутизации.
Parameter valueНетУкажите значение параметра, который будет подставлять вместо переменной <routing_parameter> в теле запроса запись со Значением колонки в определенном поле.
Вы можете создать более одного параметра. Их следует нумеровать, начиная с 0:
  • routing_parameter_0
  • routing_parameter_1

Настройка правил маршрутизации бота​

Таблица Правила маршрутизации ботов содержит условия и правила для срабатывания. при выполнении условий триггер выполняет запрос к внешней службе. Историю запросов можно найти в области связанных списков для каждой записи.

Чтобы создать правило маршрутизации, выполните следующие действия:

  1. Перейдите в API ботов → Правила маршрутизации ботов.
  2. Нажмите Создать и заполните поля.
  3. Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.

Поля формы Правило маршрутизации бота

ПолеОбязательноОписание
НаименованиеДаУкажите название правила маршрутизации.
БотДаУкажите бота, для которого необходимо настроить правило маршрутизации.
Метод ботаДаУкажите связанный метод бота.
Бизнес-правилоНетБизнес-правило генерируется автоматически, после сохранения записи правила. Оно основывается на параметры, заданные в связанных сущностях Бота и Метода бота. Это бизнес-правило вызывает системное событие, которое соответствует условиям правила.
При обновлении правила маршрутизации, бизнес-правило обновляются автоматически.
При удалении правила маршрутизации, бизнес-правило удаляется автоматически.
ТаблицаДаУкажите таблицу, для которой будет работать правило маршрутизации.
АктивенНетУстановите флажок, чтобы активировать правило.
Ответное действиеНетУстановите этот флажок, если требуется обработка назначенного ответа REST. При установленном флажке появляется вкладка Ответное действие на форме.
Направить по колонкеНетУкажите колонки, которые ссылаются на параметры маршрутизации.
Если вам нужно сопоставить несколько параметров маршрутизации с соответствующими колонками, колонки в этом поле должны быть в том же порядке, что и параметры маршрутизации в тексте запроса.

История запросов ботов​

Чтобы просмотреть историю обращений к сторонним сервисам, выполните следующие шаги:

  1. Перейдите в API ботов → История запросов ботов.
  2. Нажмите на запись, которую вам нужно просмотреть.

Поля формы История запросов бота

ПолеОписание
ЗаписьID записи, из которой был сгенерирован запрос.
Правило маршрутизацииПравило маршрутизации бота, по которому был сгенерирован запрос.
СтатусСтатус запроса. Доступные опции:
  • Отправление – запрос отправлен и успешно обработан. Сторонний сервис не выдал никаких исключений.
  • Ошибка – запрос отправлен и обработан с ошибками, которые отображаются в поле Ответ.
  • Отправлен – запрос отправлен и ожидает ответа от провайдера API.
Если ответ не получен в течение 10 минут, статус запроса меняется автоматически на Ошибка.
URLАдрес указанного запроса.
МетодМетод указанного запроса.
ЗаголовкиЗаголовки указанного запроса.
СодержимоеСодержимое указанного запроса.
ОтветОтвет запроса. Он полезен для отладки и устранения неполадок. В нем можно найти ошибки, возвращенные REST API стороннего сервиса, и ошибки, возникшие на стороне сервера, при создании или отправке запроса.