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

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

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

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

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

Слот External Request не содержит настроек HTTP-запроса, который он отправляет, он содержит ссылку на Внешний запрос из Ресурсов компании, а Внешний запрос уже в свою очередь содержит все необходимые настройки отправки запроса и обработки ответа.

1. Name — название слота, которое будет отображено в Дерево сценария. Максимальная длина значения поля — 40 символов.

   1. При сохранении Слота проверяется значение в поле:

      1. если поле пустое, выводится ошибка Please enter a slot name
      2. если в поле более 40 символов, выводится ошибка Name must contain no more than 40 characters
2. REQUEST — Внешний запрос из Ресурсов компании.

   1. При сохранении Слота проверяется значение в поле:

      1. если поле пустое, выводится ошибка Please choose a request
3. Кнопка SHOW REQUEST IN A NEW TAB — по нажатию кнопки выбранный в поле Внешний запрос открывается в новой вкладке браузера.

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

1. Чтобы создать Внешний запрос, перейдите на вкладку External Requests.

2. Нажмите кнопку Create new.
3. Заполните вкладки запроса:

Вкладка Main

1. Name* — название Внешнего запроса. Максимальная длина значения поля — 1000 символов. По достижении максимального значения далее символы не вводятся в поле.

   1. При сохранении Внешнего запроса проверяется значение в поле:

      1. если поле пустое, выводится ошибка Name is required field
2. Description — описание слота. Максимальная длина значения поля — 1000 символов. По достижении максимального значения далее символы не вводятся в поле;

3. Метод запроса* — HTTP метод для данного запроса:

   • GET

   • POST

   • PUT

   • PATCH

   • DELETE

   • HEAD

4. Endpoint* — адрес вебхука, на который будет отправлен данный запрос. Максимальная длина значения поля — 1000 символов. По достижении максимального значения далее символы не вводятся в поле.

   1. При сохранении Внешнего запроса проверяется значение в поле:

      1. если поле пустое, выводится ошибка Endpoint is required field
5. Формат значения:

   • Строка
   • Контекстная переменная в формате {{ var }}
   • Выражение или Выражение с управляющей конструкцией

Вкладка Headers

На данной вкладке можно добавить заголовки к запросу:

1. Header* — название заголовка. Максимальная длина значения поля — 1000 символов. По достижении максимального значения далее символы не вводятся в поле;

   1. Удаление пустого заголовка: Если поле не Header не заполнено, данный конкретный заголовок (строка) не будет сохранен при сохранении Внешнего запроса.

   2. Удаление крайних пробелов: Пробелы в конце и начале строки обрезаются при сохранении внешнего запроса.

   3. Использование переменных: Использование переменных не допускается.

2. Value* — значение заголовка. Максимальная длина значения поля — 1000 символов. По достижении максимального значения далее символы не вводятся в поле;

   1. Блокировка поля: Если соответствующее поле Header не заполнено, поле Value недоступно для редактирования

   2. Удаление пустого заголовка: Если поле не Value не заполнено, данный конкретный заголовок (строка) не будет сохранен при сохранении Внешнего запроса.

   3. Использование переменных: Допускается использование переменной в данном поле в формате {{ var }}. Значение переменной будет подставлено на момент сборки заголовков запроса при выполнении запроса, если переменная будет отсутствовать в Контексте Чата, то отправится заголовок с пустым значением.

   4. Выражения и управляющие конструкции: Допускается использование Выражений и Выражений с управляющими конструкциями в данном поле. Подробнее: Использование синтаксиса в External Request.

   5. Удаление крайних пробелов:

      1. Пробелы в конце и начале строки обрезаются при сохранении внешнего запроса.

      2. Пробелы в конце и начале строки НЕ обрезаются после подстановки значения переменной при выполнении запроса на этапе Сборки URL.

   6. Кнопка корзины удаляет заголовок (строку).

Вкладка Query parameters

На данной вкладке можно прописать параметры, которые будут подставлены к URL запроса в процессе Сборки URL.

1. Parameter* — название параметра. Максимальная длина значения поля — 1000 символов. По достижении максимального значения далее символы не вводятся в поле;

   1. Валидация: При сохранении Внешнего запроса проверяется соответствие имени требованиям к названию Пользовательских контекстных переменных:

      1. при несоответствии имени требованиям к названию Пользовательских контекстных переменных выводится ошибка Invalid name
   2. Удаление крайних пробелов: пробелы в конце и начале строки обрезаются при сохранении внешнего запроса.

   3. Использование переменных: не допускается

   4. Кодировка символов не латинского алфавита: допускаются пробелы, спецсимволы и не латинский символы, будет произведено кодирование значение параметра при выполнении запроса на этапе Сборки URL.

   5. Удаление пустого параметра: если поле не Parameter не заполнено, данный конкретный параметр (строка) не будет сохранен при сохранении Внешнего запроса.

2. Value* — значение параметра.

   • Удаление пустого параметра: если поле не Value не заполнено, данный конкретный параметр (строка) не будет сохранен при сохранении Внешнего запроса.

     • Использование переменных: допускается использование переменной в данном поле в формате {{ var }}. Значение переменной будет подставлено при выполнении запроса на этапе Сборки URL, если переменная будет отсутствовать в Контексте Чата, или в ней будет пустая строка, то параметр не будет подставлен.

     • Синтаксис: допускается использование Выражений и Управляющих конструкций в данном поле.

     • Удаление крайних пробелов:

       • Пробелы в конце и начале строки обрезаются при сохранении Внешнего запроса

       • Пробелы в конце и начале строки обрезаются после подстановки значения переменной при выполнении запроса на этапе Сборки URL

     • Кодировка символов не латинского алфавита: допускаются пробелы, спецсимволы и не латинский символы, будет произведено кодирование значение параметра при выполнении запроса на этапе Сборки URL Пример:

Вкладка Data

На данной вкладке можно указать данные в JSON или XML, которые будут отправлены в теле запроса (BODY).

1. Data type* — формат отправляемых данных (BODY в Request). Переключение форматов происходит по клику на название формата.

   • Доступные форматы:

     • JSON

     • XML

2. Data — шаблон тела запроса (BODY), которое будет отправлено. Максимальная длина значения поля — 1000 символов. По достижении максимального значения далее символы не вводятся в поле;

   • Формат: для корректной работы с REST API должен соблюдаться формат JSON или XML в соответствии со спецификацией API назначения.

     • При Data type: JSON

       • произвольный текст.

     • При Data type: XML

       • синтаксис XML

       • регистр тегов имеет значение — <var></Var> будет считаться незакрытым тегом и запрос не будет выполнен Важно: при копировании и вставке текста из сторонних систем в поле Data (например, тело запроса прислали в Slack), могут быть вставлены недопустимые символы кавычек, которые “сломают” тело запроса (JSON, XML) и сервер не сможет принять такой запрос. Визуально "неправильные” кавычки мало отличаются от “правильных”, но это все же другие символы. Примеры: Рекомендуется использовать двойные кавычки, так как это стандарт JSON
   • Подстановка переменных:

     • При Data type: JSON

       • В шаблоне любом месте можно указывать Контекстные переменные чата в формате {{ var }}, значения переменных будут подставлены в шаблон при выполнении запроса.
       • Если переменную не удалось найти в Контексте Чата, будет подставлено пустое значение.

     • При Data type: XML

       • В XML происходит подстановка по тегу.

       • При выбранном Data type: XML:

         • система найдет в шаблоне все XML теги (<var></var>), соответствующие названиям Контекстных переменных чата с учетом регистра

         • подставит\заменит значения (в т.ч. пустые значение) внутри этих XML тегов на значения соответствующих переменных.

         • Если переменную не удалось найти в Контекст Чата, подстановка\замена значения тега значения не будет произведена.

   • Формат значений переменных:

     • при Data type: JSON:

       • значение текстовой переменной подставляется в шаблон есть без кавычек. Если в JSON необходимо отправить текстовое значение, его необходимо обрамить в кавычки:“{{ var }}”.

     • при Data type: XML:

       • переменная должна быть записана в XML тег “как есть”, т.е без спец символов и с учетом регистра. Например, чтобы подставить значение переменной client_message в тело запроса необходимо создать XML тег<client_message></client_message>, в него и будет записано значение переменной.

   • Кодировка символов не латинского алфавита:

     • при Data type: JSON: кодирование произведено не будет.

     • при Data type: XML: символы не латинского алфавита будут закодированы при отправке запроса, не зависимо от формата текста, вписанного в поле Data. Результат запроса, Data type: XML, и в client_message записана кириллица:

Вкладка Response

На данной вкладке настраивается парсинг ответов на Внешний запрос в Пользовательские контекстные переменные.

Парсинг выполняется в процессе обработки ответа на Внешний запрос.

1. Data type* — формат отправляемых данных (BODY в Request). Переключение форматов происходит по клику на название формата.

   • Доступные форматы:

     • JSON

     • XML

     • TEST

2. Массив пар Variable - Value для парсинга данных из тела ответа на Внешний запрос в Пользовательские контекстные переменные для последующего использования их сценарии

   • Variable* — название переменной, в которую будет записано значение. Максимальная длина значения поля — 1000 символов. По достижении максимального значения далее символы не вводятся в поле;

     • При сохранении Внешнего запроса проверяется соответствие имени требованиям к названию Пользовательских контекстных переменных:

       • при несоответствии имени требованиям к названию Пользовательских контекстных переменных выводится ошибка Invalid name
   • Value* — ключ или Xpath путь к тегу xml из тела ответа, значение которого будет записано в NEW KEY. Максимальная длина значения поля — 1000 символов. По достижении максимального значения далее символы не вводятся в поле.

Парсинг тела ответа в контекстные переменные

• Возможен парсинг переменных, объектов, массивов любой вложенности

• Имена переменных и пути к значениям регистрозависимы

• Текстом прописываются названия соответствующих ключей из тела запроса;

• Через слэш (/) происходит обращение к ключам на нижних уровнях многоуровневого JSON или к вложенным тегам XML

• Обращение к соответствующему номеру элемента массива происходит с помощью чисел. Нумерация элементов массива начинается с нуля, поэтому обращение к первому элементу массива обозначается как 0.

Пример тела JSON Входящий запрос и парсинга его в настройках слота

{
           “par”: “value”,
           “content”:
                {
                    “par1”: “value1”,
                },
           “array”: [
                {
                    “par2”: “value2”,
                },
                {
                    “par3”: “value3”,
                }
            ]
}

body. — парсинг из тела запроса;

headers. — парсинг из заголовков запроса

Пример тела XML Входящий запрос и парсинга его в настройках слота

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

Во Внешних запросах допустимо использование Выражений и Управляющих конструкций в полях URL, Value на вкладке Headers и Query parameters, Data, поле Name на вкладке Response. Подробнее: Синтаксис

Примеры:

ВАЖНО: при парсинге ответа все используемые в шаблоне переменные из поля Value ищутся в ответe (Response), а не в Контексте Чата. Обращение к телу ответа происходит через переменную body. Обращение к заголовкам запроса происходит через переменную headers. Например, если ответом на 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. В Endpoint могут быть использованы Выражения и Управляющие конструкции.

2. В случае, если содержимое поля Endpoint является Контекстной переменной, непосредственно перед выполнением запроса происходит получение ее значения и подстановка в Итоговый URL внешнего запроса. Если в поле Endpoint содержится Выражение или Управляющая конструкция, происходит вычисление значения Выражения/Управляющей конструкции и запись его в Итоговый URL внешнего запроса.

   1. Корректность URL в значении Контекстной переменной не проверяется;

   2. Существование использованных Контекстных переменных не проверяется;

   3. Запрос с некорректным Итоговым URL не сможет быть обработан, ситуация будет похожа на неуспешное выполнение запроса: в request_success будет записано False, в переменную response_status_code — 499.

3. Кодирование итогового URL внешнего запроса.

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

   1. Происходит получение и кодирование имен и значений query params из вкладки Query parameters;

   2. Проверяется наличие параметров из вкладки Query parameters в Итоговый URL внешнего запроса (по имени):

      1. при наличии параметра, его значение обновляется;

      2. при отсутствии — параметр добавляется в конец Итогового URL внешнего запроса.

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

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

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

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

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

2. Получен подставляются в BODY в запрос.

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

1. Запрос отправляется однократно.

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

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

1. Таймаут ожидания ответа на внешний запрос (Response) - 30 секунд.

2. Будет произведена попытка парсинга ответа на запрос, в соответствии с настройками парсинга во вкладке Response.

   1. Если при попытке парсинга удалось найти значение по заданному пути, соответствующая Контекстная переменная будет создана\обновлена;

   2. Если при попытке парсинга не удалось найти значение по заданному пути, соответствующая Контекстная переменная не создается\не обновляется.

3. Попытка парсинга ответа на запрос будет произведена при любом коде ответа на запрос, если указаны настройки парсинга во вкладке Response.

4. При обработке ответа на запрос в переменную response_status_code записывается код ответа на запрос:

   1. При невозможности выполнить запрос будет записан код 400;

   2. При истечении таймаута в 30 секунд будет записан код 408;

   3. При отсутствии ответа от сервера будет записан код 499.

5. По итогу выполнения Внешнего запроса создается переменная request_success, в которую записывается итог выполнения запроса успех (True) или провал (False):

   1. При невозможности выполнить запрос или отсутствии ответа от сервера в request_success будет записано False;

   2. При коде ответа >=400 в request_success будет записано False;

   3. При коде ответа 200, но отсутствии (в т.ч. при пустом {} BODY) или невалидном теле для данного типа ожидаемого response, в случае если ожидается парсинг ответа (есть записи во вкладке Response) в request_success будет записано False;

   4. В остальных случаях в request_success будет записано True — запрос успешно выполнен.

6. По итогу выполнения Внешнего запроса создается переменная raw_response в формате {”результат выполнения запроса",”тело ответа”}, пример: {”success”:true,”temperature”:”-7.3”,”feels_like”:”-14.3”}.

7. Переменная складывается из двух частей:

   1. Первая часть содержит результат выполнения запроса "success":true или "success":false, являющийся дублем переменной raw_response (итог зависит от условий, описанных в п.5);

   2. При успешном выполнении, тело ответа содержит результат парсинга, заданный настройками на вкладке Response;
   3. При неуспешном выполнении, тело ответа содержит текст ошибки, полученной от внешней системы;
   4. При получении .xml от внешней системы ответ записывается строкой;

   5. При получении от внешней системы пустого {} BODY в тело ответа записывается пустая строка.

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

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

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

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

4. Если в компании нет такого Внешний запрос, то он будет импортирован и появится в списке Внешний запросов.