Действия

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

Материал из Флора AI

Версия от 18:18, 19 ноября 2024; V.Kazantsev (обсуждение | вклад) (→‎Скрипты интеграции)
Общее описание

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


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

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


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

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

        Пример данных на входе:

        data = {   "data":[

                {  "request":{

                    "datetime":"2024-09-02T13:49:05.669531",

                    "message":"Режим работы",

                    "data":[

                        {  "id":"a3d7333a-6f5a-4599-8509-bf376d067675",

                            "name":"График работы",

                            "model":"МФЦ НСК",

                            "type":"smc",

                            "param":"График работы",

                            "reply":{}      }      ]    },

                "reply":{}   }    ]       }

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

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

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

from  app.tools import apiLog

По окончании работы функции handler вызвать функцию записи лога:

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

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


Описание методов 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 робота
 {  "error": 0,

  "question": "Вопрос",

  "answer": [

    {      "messages": [

        "ответ"      ],

      "voice": ""    }  ],

  "session": null}

POST/ses/log Получение лога всех сессий начиная с date. В логе error, message и массив сессий log
  • date - начальная дата в формате %Y-%m-%d
 {  "error": 0,  "message": "success",

  "log": [

    {      "id": "0b4d87d8-6e8f-4d2b-a5e6-c4b2f08ba5d3",

      "session": "54503252-90d8-486f-87a8-b580729078a7",

      "robot": "9fd7f6f1-2cac-4f0f-a121-75c40f2b5e78",

      "channel": "default",

      "closed": true,

      "endpoint": null,

      "variables": {},

      "request": {

        "datetime": "2024-11-05T06:57:43.011249",

        "message": "вопрос",

        "data": [

          { "id": "1f8d4086-d68f-4571-92cb-f96e1d5a4b4e",

            "name": "имя элемента данных",

            "model": "имя модели",

            "type": "тип",

            "param": "параметр",

            "reply": { "class": "обнаруженный класс",

              "confidence": 1            }          }        ]

      },

      "reply": {

        "answers": [],

        "datetime": "2024-11-05T06:57:44.320266"      }    },

    .....

    ] }

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": {

    "id": "789a2605-da27-4fb8-b9ea-9400b72d0caa",

    "qas": "",

    "answered": false,

    "category": null,

    "entry": [      "1f8d4086-d68f-4571-92cb-f96e1d5a4b4e"    ],

    "nearest": null,

    "missingRunData": [      null    ]  },

  "data": [

    {      "request": {

        "datetime": "2024-11-05T12:03:14.103304",

        "message": "как поставить окружение",

        "data": [

          {   "id": "1f8d4086-d68f-4571-92cb-f96e1d5a4b4e",

            "name": "pve",

            "model": "Рыжик",

            "type": "smc",

            "param": "PVE",

            "reply": {

              "class": "PVE",

              "confidence": 1            }          }        ]      },

      "reply": {

        "answers": [          {

            "messages": [              "скачать и поставить"            ],

            "voice": ""          }    ],

        "datetime": "2024-11-05T12:03:14.127868"      }    }  ],

  "variables": {},

  "history": [

    {      "id": "2d5853d3-2d62-49f9-b2cd-329937c2985b",

      "session": "4fa212dd-645f-48b5-af90-6cab208de1d2",

      "robot": "9fd7f6f1-2cac-4f0f-a121-75c40f2b5e78",

      "channel": "default",

      "closed": false,

      "endpoint": null,

      "variables": {},

      "request": {

        "datetime": "2024-11-05T12:03:14.103304",

        "message": "как поставить окружение",

        "data": [

          {            "id": "1f8d4086-d68f-4571-92cb-f96e1d5a4b4e",

            "name": "pve",

            "model": "Рыжик",

            "type": "smc",

            "param": "PVE",

            "reply": {

              "class": "PVE",

              "confidence": 1            }          }        ]      },

      "reply": {

        "answers": [          {            "messages": [  "скачать и поставить"    ],

            "voice": ""

          },

          { "messages": [    "Фраза 2"   ],

            "voice": ""          }        ],

        "datetime": "2024-11-05T12:03:14.127868"      }    }  ]}

Группа методов 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": "9fd7f6f1-2cac-4f0f-a121-75c40f2b5e78",

    "name": "test",

    "description": "",

    "voice": "",

    "session": {      "lifetime": 600    },

    "models": {},

    "servicedata": {},

    "exceptions": {},

    "actions": {},

    "holidays": [],

    "timeintervals": {

      "name": {

        "weekdays": [ 1, 2, 3, 4, 5, 6,  7  ],

        "dates": [  0,  1,  2,   3, 4,  5, 6,  7,  8,  9, 10,  11, 12,13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31],

"months": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ],

"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": "bc1cb1a1-c64e-46a1-b422-1a48de9ddacb",

    "name": "pve",

    "type": "smc",

    "model": "Рыжик",

    "param": "PVE",

    "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": "6500dd0f-4bd1-43b3-9fd4-145eb7210c45",

    "name": "pve",

    "entry": [ [ "bc1cb1a1-c64e-46a1-b422-1a48de9ddacb"]],

    "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} Получение списка скриптов
Входные параметры отсутствуют [  {    "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>/<параметры>
 [

  "ответ эмулятора"

]

Источник — https://wiki.connect2ai.net/index.php?title=SES._Руководство_пользователя&oldid=1937