SES. Руководство пользователя: различия между версиями

Версия от 12:14, 22 апреля 2025

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

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

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

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, т.е. где именно он нашелся

Описание методов 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":"значение"} 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>		"ответ эмулятора"

@@ Строка 65: / Строка 65: @@
 * '''reply_datetime''' - время сразу по получению ответа, также без учета таймзоны.<br /> <span style="color:red">Внимание - не используйте '''apiRequest или apiLog''' для данных содержащих пароли в открытом виде, чтобы они не попали в лог</span>
+====== Функция '''''getData''''' ======
 '''''Для упрощения поиска информации можно использовать функцию getData''''' (''from app.tools import getData''), нужна для извлечения конкретных данных из сессии, можно отправить либо всю переменную сессии, либо 'data' из сессии. Пример поиска цифрового кода заявления, выявленного моделью see 'number', поиск только в последнем сообщении диалога: