SES. Руководство пользователя

Общее описание

Сервис предназначен для создания сценарных машин и обеспечения их работы.

Термины и определения

Script engine service (SES) - сервис обеспечения работы и создания сценарных машин. Swagger UI – интерактивная веб-консоль с кратким описанием методов API и возможностью выполнять запросы к сервису SES в реальном времени

Скрипты интеграции

Для взаимодействия со сторонними сервисами используются скрипты интеграции на языке python. Скрипт интеграции должен содержать функцию handler(data={}, session_id=None, channel='default').

Пример данных на входе можно посмотреть в методе ses GET/ses/session/{robot_id}/{session_id}

Функция должна исходя из полученных данных запросить ответ у стороннего сервиса. Запрос необходимо выполнить в блоке try/except. Скрипт не должен выдавать ошибку в основное приложение, все исключения должны быть обработаны внутри скрипта.

---

Функция apiRequest

Для отправки запроса рекомендуется использовать функцию apiRequest. Функция сделает все необходимые записи в лог интеграции. Пример:

from  app.tools import apiRequest

status, reply = apiRequest(name="наименование скрипта",method='get',sessiondata=data,url=url,timeout=(1,10))

• status, reply - http код ответа (например 200) и ответ без изменений и сериализации.

• name = название вызываемого метода, для отчетности

• sessiondata - это data в handler, которая туда прилетает

• method - метод запроса-ответа

после этих параметров в функцию apiRequest отправить все нужные параметры, как при вызове requests, они будут переданы один к одному.

Из функции handler можно передать или изменить переменную (в рамках текущей сессии): data['variables']={'new_var': 'новое_значение'}

Функция handler должна возвращать ответ в виде return { "text": "Текст ответа.", 'answered': True}, {}

• text - текст ответа

• answered - получен ли ответ (True или False)

Если в скрипте интеграции не используются запросы к api стороннего сервиса через http, необходимо предусмотреть запись в лог (запись в лог встроена в функцию apiRequest и при ее использовании отдельно писать в лог не надо). Для этого необходимо импортировать библиотеку:

from  app.tools import apiLog

---

Функция apiLog

Если в скрипте интеграции не используются запросы к api, по окончании работы функции handler вызвать функцию записи лога:

apiLog(data=data,name="",url="",request={},reply_code=200,reply=None,request_datetime=None,reply_datetime=None)

• data - тот же массив который был на входе

• name - наименование или короткое описание скрипта

• url - адрес запроса к стороннему сервису (если есть)

• request - текст запроса

• reply_code - код ответа (стандартный код http)

• reply - необработанный ответ стороннего сервиса

• request_datetime - время перед запросом, без учета таймзоны, получить лучше так request_datetime=datetime.now(timezone.utc)

• reply_datetime - время сразу по получению ответа, также без учета таймзоны.
  Внимание - не используйте apiRequest или apiLog для данных содержащих пароли в открытом виде, чтобы они не попали в лог

---

Функция getData

Для упрощения поиска информации можно использовать функцию getData (from app.tools import getData), нужна для извлечения конкретных данных из сессии, можно отправить либо всю переменную сессии, либо 'data' из сессии. Пример поиска цифрового кода заявления, выявленного моделью see 'number', поиск только в последнем сообщении диалога:

for j in getData(data=data,filter={'type':'see','model':'number'},depth=1):

kod_zayavl=str(int(j['param']))

break

Параметры функции

• data - или 'data' из сессии или переменная сессии

• filter - словарь ключевых полей и их значений - поиск сработает если все данные совпадут

• depth - отвечает за глубину поиска в истории, по умолчанию 1, т.е. искать только в последнем сообщении. Возвращает список всех найденных данных, добавляя в каждый элемент depth, т.е. где именно он нашелся

---

Отложенные задания

Для выполнения отложенных заданий необходимо

1. получить ссылку на базу данных текущего робота
2. в таблицу "crons" внести внести время и python код который должен выполниться в указанное время.

Пример отложенного сообщения в телеграм:
    # Формируем задачу в крон

    error, db = get_db(data['robot'])

    if error:

        return { 'text': 'А я тебе ошибку базы данных привез: '+str(db), 'answered': False }, {}

    dt = int(datetime.strptime(date['date']+' '+date['time'],'%Y-%m-%d %H:%M').timestamp())

    # А вот тут создадим код для выполнения задачи

    url = f'https://api.telegram.org/bot{token}/sendMessage'

    data = json.dumps({'chat_id': chat_id, 'text': message})

    data = base64.b64encode(data.encode("utf-8")).decode("utf-8")

    code = """

        import requests, json, base64

        try:

            data=\"{1}\"

            data=base64.b64decode(data.encode('utf-8')).decode('utf-8')

            requests.post(\"{0}\", data=json.loads(data), timeout = (5, 10))

        except Exception as error:

            logging.error(traceback.format_exc())

    """.format(url,data).replace("        ","")

    error, result = db.create(table='crons',data={

        'id': str(uuid.uuid4()),

        'name':'Задача-напоминание для '+username,

        'datetime': dt,

        'code': code })

---

Пользовательские таблицы базы данных

В составе большинства продуктов используется служебная файловая база данных. В SES возможно использование служебной базы в скриптах интеграции. Для этого нужно:

1. Импортировать функцию получения объекта БД (from app.db import get_db)
2. Получить объект БД error, db = get_db(data['robot']) if error: return { 'text': 'А я тебе ошибку базы данных привез: '+str(db), 'answered': False }, {}
3. Объявить структуру пользовательской таблицы, создав запись в т

Описание методов API

Запросы осуществляются по протоколу HTTP 1.1 на адрес сервера с доступным сервисом SES. По умолчанию используется порт 6189/tcp.

Авторизация запросов не требуется. HTTP-запросы должны содержать заголовок "accept: application/json"

Ответ сервиса представляет собой JSON или текстовый документ в кодировке UTF-8, или двоичный файл.

Содержимое документа зависит от результата выполнения запроса. При наличии ошибки в качестве ответа вернется переменная error=1 и описание в переменной message. Для удобства проверки методов по ссылке http://АДРЕС:6190 будет отображен интерфейс swagger со всеми методами с возможностью их проверки.

Методы API

Группа методов ses
для некоторых путей, где используется {robot_id} - это обращение к версии черновика, чтобы обращаться r продовой версии - нужен постфикс "_prod", для бэкапа "_backup" актуально для методов - получения данных робота  GET/ses/robot/get/{id} - применение настроек робота GET/ses/robot/commit/{id} - экспорт робота GET/ses/robot/export/{id} - список скриптов GET/ses/robot/script/list/{robot} - получение скрипта GET/ses/robot/script/get/{robot}/{id} - список ЭД GET/ses/robot/data/list/{robot} - получение ЭД GET/ses/robot/data/get/{robot}/{id} - список КТ GET/ses/robot/endpoint/list/{robot} - получение КТ GET/ses/robot/endpoint/get/{robot}/{id} - метода ask (отладчика) POST/ses/ask/{robot_id} - данные сессии (отладчика) GET/ses/session/{robot_id}/{session_id}
POST/ses/ask/{robot_id}	Получение ответа на запрос пользователя. Метод для отладки робота
text - текст запроса channel - id канала session - uuid сессии, если это не первый запрос в сессии tts - вернуть результат синтеза (1- вернуть, 0 - не выполнять синтез) variables - словарик с переменными {"переменная1":"значение","переменнаяN":"значение"} handler - python скрипт для изменения ответов метода под требования внешних систем, подробнее в следующем разделе. в поле имя файла без расширения. audio - аудиофайл с запросом, текст запроса будет получен распознаванием audio robot_id - id робота isDebugger - флаг отладки (0/1)		{  "error": 0,   "question": "Вопрос",   "answer": [     {      "messages": [         "ответ"      ],       "voice": ""    }  ],   "session": null}
POST/ses/log	Получение лога всех сессий начиная с date. В логе error, message и массив сессий log (log содержит информацию о каждой сессии и запросы с ответами)
date - начальная дата в формате %Y-%m-%d		{  "error": 0,  "message": "success",   "log": [     {"id": ",.....", "session": "......", "robot": ".....",       "channel": "......", "closed": true/false, "endpoint": ".....",       "variables": {},       "request": {.......},      "reply": { ..... }    },     ..... ] }
GET/ses/session/{robot_id}/{session_id}	Выдает параметры сессии. Для отображения на боковой панели тестирования в UPS. Основные блоки результата:
robot_id - id робота session_id - id незакрытой сессии		{ "started": "2024-11-05 15:03:14", "modified": "2024-11-05 15:03:14", "current": {.....}, "data": [   {   "request": { },    "reply": {  }  } ], "variables": {}, "history": [   {   "id": ".....", "session": ".....", "robot": ".....",    "channel": ".....", "closed": false, "endpoint": ".....",    "variables": {},    "request": {.....},    "reply": {.....}  } ]}
GET/ses/widget/config	Отдает конфигурацию виджета скрипту виджета
token - ключ виджета		На выходе содержимое настрое web канала из конфигурационного файла
Группа методов ses/robot/
POST/ses/robot/add	Создание нового робота. На выходе id созданного робота или сообщение об ошибке
name - имя нового робота		{  "error": 0,   "id": "2fd2f909-2069-4b20-a725-3a598c83f886"}
GET/ses/robot/apply/{id}	Применение робота. Переводит черновик робота в статус prod. Если до этого был prod вариант - становится backup.
id - идентификатор робота		{  "error": 0,   "message": "success"}
GET/ses/robot/cleardraft/{id}	Обнуление черновика рабочей версией робота
id - идентификатор робота		{  "error": 0,   "message": "success"}
GET/ses/robot/commit/{id}	Применение текущих изменений настроек робота. Применимо ко всем версиям (черновик, рабочая, резервная копия)
id - идентификатор робота		{  "error": 0,   "message": "success"}
DELETE/ses/robot/delete/{id}	Удаление всех версий робота
id - идентификатор робота		{  "error": 0,   "message": "success"}
GET/ses/robot/export/{id}	Выгрузка робота в архив.
id - идентификатор робота		zip файл с именем = идентификатор робота
GET/ses/robot/get/{id}	Выгрузка основных настроек робота
id - идентификатор робота		{  "error": 0,   "data": { "id": ".....", "name": ".....","description": "",     "voice": "", "session": {      "lifetime": 600    },     "models": {},"servicedata": {},"exceptions": {},"actions": {},     "holidays": [],     "timeintervals": {       "name": {"weekdays": [ ..... ], "dates": [  ..... ], "months": [.....], "days": "all", "intervals": [ [ 0,  1440 ] ] }}}}
POST/ses/robot/import/{id}	Загрузка архива робота в черновик существующего робота
zip - файл с архивом робота id - идентификатор робота		{  "error": 0,   "message": "success"}
GET/ses/robot/list	Получение списка роботов
Входные параметры отсутствуют		[  {  "id": "9fd7f6f1-2cac-4f0f-a121-75c40f2b5e78",     "name": "test",     "hasProd": true,     "hasBackup": true  } ]
POST/ses/robot/modify/{id}	Изменение основных настроек робота. Формат data как в ответе метода GET/ses/robot/get/{id}
data - json строка с новыми настройками робота id - идентификатор робота		{  "error": 0,   "message": "success"}
GET/ses/robot/restore/{id}	Откат рабочей версии из бэкапа. Резервная копия становится рабочей, и удаляется, а черновик остается без изменений
id - идентификатор робота		{  "error": 0,   "message": "success"}
Группа методов ses/robot/data
POST/ses/robot/data/add/{robot}	Добавление элемента данных
data - json строка с параметрами элемента данных robot - идентификатор робота		{  "error": 0,   "message": "success"}
DELETE/ses/robot/data/delete/{robot}/{id}	Удаление элемента данных
id - идентификатор элемента данных robot - идентификатор робота		{  "error": 0,   "message": "success"}
GET/ses/robot/data/get/{robot}/{id}	Получение настроек элемента данных
id - идентификатор элемента данных robot - идентификатор робота		{  "error": 0,   "data": { "id": ".....",  "name": ".....", "type": "smc",     "model": ".....", "param": ".....","weight": 0, "slaveData": [], "forEndpointRunOnly": true, "actions": {}  } }
GET/ses/robot/data/list/{robot}	Получение списка элементов данных
robot - идентификатор робота		[  {    "id": "bc1cb1a1-c64e-46a1-b422-1a48de9ddacb",     "name": "pve",     "type": "smc"  } ]
POST/ses/robot/data/modify/{robot}/{id}	Изменение элемента данных. Формат data как на выходе метода GET/ses/robot/data/get/{robot}/{id}
data - json строка с параметрами элемента данных robot - идентификатор робота id - идентификатор элемента данных		{  "error": 0,   "message": "success"}
Группа методов ses/robot/endpoint
POST/ses/robot/endpoint/add/{robot}	Создание конечной точки. Формат data как на выходе метода GET/ses/robot/endpoint/get/{robot}/{id}
data - json строка с параметрами конечной точки robot - идентификатор робота		{  "error": 0,   "id": "8576593b-b0d8-4b03-a623-74f3132356ea"}
DELETE/ses/robot/endpoint/delete/{robot}/{id}	Удаление конечной точки.
robot - идентификатор робота id - идентификатор конечной точки		{  "error": 0,   "message": "success"}
GET/ses/robot/endpoint/get/{robot}/{id}	Получение настроек конечной точки
robot - идентификатор робота id - идентификатор конечной точки		{  "error": 0,   "data": { "id": ".....", "name": ".....", "entry": [ [ "....."]], "run": [],     "actions": {       "default": [ {"action": "say","type": "linear","text": [ "....."] },         { "action": "следующее действие"}      ]    }  } }
GET/ses/robot/endpoint/list/{robot}	Получение списка конечных точек робота
robot - идентификатор робота		[  {    "id": "8576593b-b0d8-4b03-a623-74f3132356ea",     "name": "точка 1",     "entry": []  },   {    "id": "6500dd0f-4bd1-43b3-9fd4-145eb7210c45",     "name": "точка 2",     "entry": [      [        "bc1cb1a1-c64e-46a1-b422-1a48de9ddacb"      ]    ]  }]
POST/ses/robot/endpoint/modify/{robot}/{id}	Изменение конечной точки. Формат data как на выходе метода GET/ses/robot/endpoint/get/{robot}/{id}
data - json строка с параметрами элемента данных id - идентификатор элемента данных robot - идентификатор робота		{  "error": 0,   "message": "success"}
Группа методов ses/robot/script
POST/ses/robot/script/add/{robot}	Добавление нового скрипта. Формат data как в ответе метода GET/ses/robot/script/get/{robot}/{id}
data - json строка с параметрами скрипта robot - идентификатор робота		{  "error": 0,   "message": "success"}
DELETE/ses/robot/script/delete/{robot}/{id}	Удаление скрипта
robot - идентификатор робота id - идентификатор скрипта		{  "error": 0,   "message": "success"}
GET/ses/robot/script/get/{robot}/{id}	Получение текста скрипта
robot - идентификатор робота id - идентификатор скрипта		{  "error": 0,   "data": {     "id": "6a9f91b6-9634-4079-ac2b-60a944922c61",     "name": "Наименование скрипта",     "code": "Текст скрипта"  } }
GET/ses/robot/script/list/{robot}	Получение списка скриптов
robot - идентификатор робота		[  {    "id": "9b9d83b7-d5c3-49e6-9bd4-a123a9047939",     "name": "наименование1" },   {    "id": "48b508ba-a32b-4ada-bcc3-66ce26d81c6a",     "name": "наименование2" }]
POST/ses/robot/script/modify/{robot}/{id}	Изменение скрипта.Формат data как в ответе метода GET/ses/robot/script/get/{robot}/{id}
data - json строка с параметрами элемента данных id - идентификатор скрипта robot - идентификатор робота		{  "error": 0,   "message": "success"}
Группа методов ses/testapi для отладки скриптов интеграции
GET/ses/testapi/list	Получение списка эмуляторов сервисов интеграции
Входные параметры отсутствуют		[  "service1",   "service2",   "serviceN"]
POST/ses/testapi/{request}	Получение ответа эмулятора сервиса интеграции
request - запрос вида <service1>		"ответ эмулятора"
GET/ses/testapi/{request}	Получение ответа эмулятора сервиса интеграции
request - запрос вида <service1>		"ответ эмулятора"

Постобработка методов api

Для метода POST/ses/ask/{robot_id} можно изменить формат данных ответа.

Для этого необходимо подготовить скрипт на python в папке /opt/ses/handlers/api/ask/ . Скрипт должен содержать функцию handler(reply={}), Функция должна вернуть переформатированный ответ. Чтобы воспользоваться скриптом необходимо его имя без разрешения указать в поле "handler" при запросе метода.

Аналогично и для метода ask websocket протокола - файл положить в /opt/ses/handlers/websockets/ask/ . Далее в любом запросе указать обработчик {тут всё, что ты и так отправляешь, 'handlers': { 'ask': '__telegram' }} } . начиная с этого запроса обработчик будет действовать в течение сессии пока не отправишь 'handlers': {} . Для других полей запросов в канале websocket аналогично.

В составе поставки ses есть файл примера __telegram.py (префикс 2 подчеркивания - такой файл будет переписан при обновлении, любой другой, останется после обновления)