chatme.ai
Search…
⌃K

Запросы во внешние системы | Слот External Request

Назначение и общая информация

Слот External Request предназначен для интеграции Агента c внешними ИТ системами по протоколу HTTP (REST API или GraphQL, например). При обработке данного слота в Сценарий происходит выполнения HTTP-запроса к API внешней системы, а также получение и обработка ответа на этот запрос.

Создание и настройки слота

Атрибуты слота

Слот External Request не содержит настроек HTTP-запроса, который он отправляет, он содержит ссылку на Внешний запрос из Ресурсов компании, а Внешний запрос уже в свою очередь содержит все необходимые настройки отправки запроса и обработки ответа.
  1. 1.
    NAME — название слота, которое будет отображено в Дерево сценария. Максимальная длина значения поля — 40 символов.
  2. 2.
    REQUEST — Внешний запрос из Ресурсов компании.

Создание Внешнего запроса в ресурсах Компании

  1. 1.
    Чтобы создать Внешний запрос, перейдите на вкладку External Requests.
  2. 2.
    Нажмите кнопку Create new.
  3. 3.
    На вкладке Main заполните поля:
    1. 1.
      Name — название слота. Максимальная длина значения поля — 1000 символов. По достижении максимального значения далее символы не вводятся в поле;
    2. 2.
      Description — описание слота. Максимальная длина значения поля — 1000 символов. По достижении максимального значения далее символы не вводятся в поле;
    3. 3.
      Метод запроса — HTTP метод для данного запроса:
      • GET
      • POST
      • PUT
      • PATCH
      • DELETE
      • HEAD
    4. 4.
      Endpoint — адрес вебхука, на который будет отправлен данный запрос. Максимальная длина значения поля — 1000 символов. По достижении максимального значения далее символы не вводятся в поле.
  4. 4.
    На вкладке Headers можно добавить заголовки к запросу:
    1. 1.
      New name — название заголовка. Максимальная длина значения поля — 1000 символов. По достижении максимального значения далее символы не вводятся в поле;
    2. 2.
      Value — значение заголовка. Максимальная длина значения поля — 1000 символов. По достижении максимального значения далее символы не вводятся в поле;
      • Использование переменных: допускается использование переменной в данном поле в формате $var. Значение переменной будет подставлено на момент сборки заголовков запроса при выполнении запроса, если переменная будет отсутствовать в Контекстt Чата, то отправится заголовок с пустым значением$
      • Конкатенация: допускается конкатенация строк и переменных в данном поле:

Использование синтаксиса в External Request

Во Внешних запросах допустимо использование Выражений и Управляющих конструкций в полях URL, Value на вкладке Headers и Query parameters, Data, поле Name на вкладке Response. Подробнее: Переход на новый синтаксис
Примеры:
ВАЖНО: при парсинге ответа все используемые в шаблоне переменные ищутся в теле ответа, а не в Контексте Чата. Обращение к телу ответа происходит через переменную body. Например, если ответом на ER является JSON объект: {“one”: {“two”: [0, 1, 2]}}, то в переменную resp_body будет сохранен весь JSON-объект (словарь) {“one”: {“two”: [1, 2, 3]}}, в переменную resp_one – будет сохранен объект (словарь) {“two”: [1, 2, 3]}, в переменную resp_two будет сохранено целое число 1. Переменная resp_invalid не будет сохранена, т.к. к телу ответа нужно обращаться через переменную body.

Работа слота

Процесс выполнения слота External Request:

1. Определение внешнего запроса для выполнения

В Обученной модели агента (в каждом слоте External Request) хранится копия своего Внешнего запроса из Списка внешних запросов, созданная на момент последнего Обучения Агента.

2. Сборка итогового URL внешнего запроса

  1. 1.
    В Endpoint могут быть использованы Выражения и Управляющие конструкции.
  2. 2.
    В случае, если содержимое поля Endpoint является Контекстной переменной, непосредственно перед выполнением запроса происходит получение ее значения и подстановка в Итоговый URL внешнего запроса. Если в поле Endpoint содержится Выражение или Управляющая конструкция, происходит вычисление значения Выражения/Управляющей конструкции и запись его в Итоговый URL внешнего запроса.
    1. 1.
      Корректность URL в значении Контекстной переменной не проверяется;
    2. 2.
      Существование использованных Контекстных переменных не проверяется;
    3. 3.
      Запрос с некорректным Итоговым URL не сможет быть обработан, ситуация будет похожа на неуспешное выполнение запроса: в request_success будет записано False, в переменную response_status_code499.
  3. 3.
    Кодирование итогового URL внешнего запроса.
    1. 1.
      Система проверяет наличие недопустимых символов в итоговом URL внешнего запроса и производит их кодирование
      В примере в Endpoint записан с недопустимыми символами — кириллицей, поэтому в Итоговый URL внешнего запроса он попадет в закодированном виде: http://example.com/%D0%B0%D0%B1%D0%B2%D0%B3%D0%B4
    2. 2.
      Если Итоговый URL внешнего запроса содержит уже закодированные части (например, параметры), система это распознает и не произведет повторной кодировки.
      В примере в Endpoint записан уже закодированный URL, поэтому в Итоговый URL внешнего запроса он попадет без изменений в виде http://example.com/abc%253D
    3. 3.
      Если Итоговый URL внешнего запроса содержит и закодированные части и недопустимые незакодированные символы, система это распознает закодирует только недопустимые незакодированные символы
      В примере будет закодирована только часть еюя и в Итоговый URL внешнего запроса попадет http://example.com/%D0%B5%D1%8E%D1%8F%20abc%253D
  4. 4.
    После получения Итоговый URL внешнего запроса происходит обновление и подстановка параметров запроса — query params — из вкладки Query parameters.
    1. 1.
      Происходит получение и кодирование имен и значений query params из вкладки Query parameters;
    2. 2.
      Проверяется наличие параметров из вкладки Query parameters в Итоговый URL внешнего запроса (по имени):
      1. 1.
        при наличии параметра, его значение обновляется;
      2. 2.
        при отсутствии — параметр добавляется в конец Итогового URL внешнего запроса.

3. Сборка заголовков запроса

  1. 1.
    Перед отправкой запроса происходит получение имен и значений заголовков из вкладки Headers.
  2. 2.
    Полученные заголовки подставляются в запрос.

4. Сборка тела запроса

  1. 1.
    Перед отправкой запроса происходит получение значения тела запроса из вкладки Data.
  2. 2.
    Получен подставляются в BODY в запрос.

5. Отправка запроса

  1. 1.
    Запрос отправляется однократно.
  2. 2.
    При разрыве соединения в течение таймаута повторных попыток отправить запрос также не производится.

6. Прием ответа и запись контекстных переменных

  1. 1.
    Таймаут ожидания ответа на внешний запрос (Response) - 30 секунд.
  2. 2.
    Будет произведена попытка парсинга ответа на запрос, в соответствии с настройками парсинга во вкладке Response.
    1. 1.
      Если при попытке парсинга удалось найти значение по заданному пути, соответствующая Контекстная переменная будет создана\обновлена;
    2. 2.
      Если при попытке парсинга не удалось найти значение по заданному пути, соответствующая Контекстная переменная не создается\не обновляется.
  3. 3.
    Попытка парсинга ответа на запрос будет произведена при любом коде ответа на запрос, если указаны настройки парсинга во вкладке Response.
  4. 4.
    При обработке ответа на запрос в переменную response_status_code записывается код ответа на запрос:
    1. 1.
      При невозможности выполнить запрос будет записан код 400;
    2. 2.
      При истечении таймаута в 30 секунд будет записан код 408;
    3. 3.
      При отсутствии ответа от сервера будет записан код 499.
  5. 5.
    По итогу выполнения Внешнего запроса создается переменная request_success, в которую записывается итог выполнения запроса успех (True) или провал (False):
    1. 1.
      При невозможности выполнить запрос или отсутствии ответа от сервера в request_success будет записано False;
    2. 2.
      При коде ответа >=400 в request_success будет записано False;
    3. 3.
      При коде ответа 200, но отсутствии (в т.ч. при пустом {} BODY) или невалидном теле для данного типа ожидаемого response, в случае если ожидается парсинг ответа (есть записи во вкладке Response) в request_success будет записано False;
    4. 4.
      В остальных случаях в request_success будет записано True — запрос успешно выполнен.
  6. 6.
    По итогу выполнения Внешнего запроса создается переменная raw_response в формате {”результат выполнения запроса",”тело ответа”}, пример: {”success”:true,”temperature”:”-7.3”,”feels_like”:”-14.3”}.
  7. 7.
    Переменная складывается из двух частей:
    1. 1.
      Первая часть содержит результат выполнения запроса "success":true или "success":false, являющийся дублем переменной raw_response (итог зависит от условий, описанных в п.5);
    2. 2.
      При успешном выполнении, тело ответа содержит результат парсинга, заданный настройками на вкладке Response;
    3. 3.
      При неуспешном выполнении, тело ответа содержит текст ошибки, полученной от внешней системы;
    4. 4.
      При получении .xml от внешней системы ответ записывается строкой;
    5. 5.
      При получении от внешней системы пустого {} BODY в тело ответа записывается пустая строка.

Экспорт и импорт внешних запросов

При экспорте Агента происходит также экспорт всех Внешних запросов, содержащихся в его Обученной модели агента. Агент с включенными в него Внешними запросами экспортируется в виде файла формата .cfg. При импорте Агента происходит импорт используемых в нем Внешний запрос, при этом:
  1. 1.
    Если в компании есть Внешний запрос с идентичным названием и содержимым, дублирования Внешнего запроса не происходит. В импортированном Агенте будет использован уже существующий Внешний запрос. В остальных случаях будет создан новый Внешний запрос;
  2. 2.
    Если в компании есть Внешний запрос с идентичным названием, но отличающимся содержимым, будет создан дубликат этого Внешнего запроса с автоматически сгенерированным именем:
  3. 3.
    Если в компании есть Внешний запрос с отличающимся названием, но идентичным содержанием, то Внешний запрос из конфига будет импортирован.
  4. 4.
    Если в компании нет такого Внешний запрос, то он будет импортирован и появится в списке Внешний запросов.