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 символов. По достижении максимального значения далее символы не вводятся в поле.
  5. 5.
    Формат значения:
    • Строка
      image.png
      ​
    • Контекстная переменная в формате {{ var }}
      image.png
    • Выражение или Управляющая конструкция
      image.png
      ​

Вкладка Headers
​

На данной вкладке можно добавить заголовки к запросу:
  1. 1.
    New name* — название заголовка. Максимальная длина значения поля — 1000 символов. По достижении максимального значения далее символы не вводятся в поле;
    • Удаление пустого заголовка: Если поле не New name* не заполнено, данный конкретный заголовок (строка) не будет сохранен при сохранении Внешнего запроса.
    • Удаление крайних пробелов: пробелы в конце и начале строки обрезаются при сохранении внешнего запроса.
    • Использование переменных: использование переменных не допускается.
  2. 2.
    Value* — значение заголовка. Максимальная длина значения поля — 1000 символов. По достижении максимального значения далее символы не вводятся в поле;
    • Использование переменных: допускается использование переменной в данном поле в формате {{ var }}. Значение переменной будет подставлено на момент сборки заголовков запроса при выполнении запроса, если переменная будет отсутствовать в Контексте Чата, то отправится заголовок с пустым значением.
    • Синтаксис: допускается использование Выражений и Управляющих конструкций в данном поле.
    • Удаление крайних пробелов:
      • Пробелы в конце и начале строки обрезаются при сохранении Внешнего запроса.
      • Пробелы в конце и начале строки НЕ обрезаются после подстановки значения переменной при выполнении запроса на этапе Сборки URL.

Вкладка Query parameters

​
​
На
данной вкладке можно прописать параметры, которые будут подставлены к URL запроса в процессе Сборки URL.
  1. 1.
    New name* — название параметра. Максимальная длина значения поля — 1000 символов. По достижении максимального значения далее символы не вводятся в поле;
    • Удаление пустого параметра: если поле не New name не заполнено, данный конкретный параметр (строка) не будет сохранен при сохранении Внешнего запроса.
    • Удаление крайних пробелов: пробелы в конце и начале строки обрезаются при сохранении внешнего запроса.
    • Использование переменных: не допускается
    • Кодировка символов не латинского алфавита: допускаются пробелы, спецсимволы и не латинский символы, будет произведено кодирование значение параметра при выполнении запроса на этапе Сборки URL.
  2. 2.
    Value* — значение параметра.
    • Удаление пустого параметра: если поле не Value не заполнено, данный конкретный параметр (строка) не будет сохранен при сохранении Внешнего запроса.
      • Использование переменных: допускается использование переменной в данном поле в формате {{ var }}. Значение переменной будет подставлено при выполнении запроса на этапе Сборки URL, если переменная будет отсутствовать в Контексте Чата, или в ней будет пустая строка, то параметр не будет подставлен.
      • Синтаксис: допускается использование Выражений и Управляющих конструкций в данном поле.
      • Удаление крайних пробелов:
        • Пробелы в конце и начале строки обрезаются при сохранении Внешнего запроса
        • Пробелы в конце и начале строки обрезаются после подстановки значения переменной при выполнении запроса на этапе Сборки URL​
      • Кодировка символов не латинского алфавита: допускаются пробелы, спецсимволы и не латинский символы, будет произведено кодирование значение параметра при выполнении запроса на этапе Сборки URL Пример:
        image.png
        ​

Вкладка Data

​
​
На данной вкладке можно указать данные в JSON или XML, которые будут отправлены в теле запроса (BODY).
  1. 1.
    Data type — формат отправляемых данных (BODY в Request). Переключение форматов происходит по клику на название формата.
    • Доступные форматы:
      • JSON
      • XML
  2. 2.
    Data — шаблон тела запроса (BODY), которое будет отправлено. Максимальная длина значения поля — 1000 символов. По достижении максимального значения далее символы не вводятся в поле;
    • Формат: для корректной работы с REST API должен соблюдаться формат JSON или XML в соответствии со спецификацией API назначения.
      • При Data type: JSON
        • произвольный текст.
      • При Data type: XML
        • синтаксис XML
        • регистр тегов имеет значение — <var></Var> будет считаться незакрытым тегом и запрос не будет выполнен Важно: при копировании и вставке текста из сторонних систем в поле Data (например, тело запроса прислали в Slack), могут быть вставлены недопустимые символы кавычек, которые “сломают” тело запроса (JSON, XML) и сервер не сможет принять такой запрос. Визуально "неправильные” кавычки мало отличаются от “правильных”, но это все же другие символы. Примеры:
          image.png
           Рекомендуется использовать двойные кавычки, так как это стандарт JSON
    • Подстановка переменных:
      • При Data type: JSON
        • В шаблоне любом месте можно указывать Контекстные переменные чата в формате {{ var }}, значения переменных будут подставлены в шаблон при выполнении запроса.
          image.png
          ​
        • Если переменную не удалось найти в Контексте Чата, будет подставлено пустое значение.
      • При 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 записана кириллица:
        image.png
        ​

Вкладка Response

​
​
На данной вкладке настраивается парсинг ответов на Внешний запрос в Пользовательские контекстные переменные.
Парсинг выполняется в процессе обработки ответа на Внешний запрос.
  1. 1.
    Data type* — формат отправляемых данных (BODY в Request). Переключение форматов происходит по клику на название формата.
    • Доступные форматы:
      • JSON
      • XML
      • TEST
  2. 2.
    Массив пар Variable - Value для парсинга данных из тела ответа на Внешний запрос в Пользовательские контекстные переменные для последующего использования их сценарии
    • Variable* — название переменной, в которую будет записано значение. Максимальная длина значения поля — 1000 символов. По достижении максимального значения далее символы не вводятся в поле;
      При указании Variable обратите внимание на требования к именам Пользовательских контекстных переменных.
    • Value* — ключ или Xpath путь к тегу xml из тела ответа, значение которого будет записано в NEW KEY. Максимальная длина значения поля — 1000 символов. По достижении максимального значения далее символы не вводятся в поле.

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

  • Возможен парсинг переменных, объектов, массивов любой вложенности
  • Имена переменных и пути к значениям регистрозависимы
  • Текстом прописываются названия соответствующих ключей из тела запроса;
  • Через слэш (/) происходит обращение к ключам на нижних уровнях многоуровневого JSON или к вложенным тегам XML
  • Обращение к соответствующему номеру элемента массива происходит с помощью чисел. Нумерация элементов массива начинается с нуля, поэтому обращение к первому элементу массива обозначается как 0.

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

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

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

​
image.png
​
​
image.png
​

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

Во Внешних запросах допустимо использование Выражений и Управляющих конструкций в полях URL, Value на вкладке Headers и Query parameters, Data, поле Name на вкладке Response. Подробнее: Переход на новый синтаксис​
Примеры:
​
image.png
​
​
image.png
​
​
image.png
​
​
image.png
​
ВАЖНО: при парсинге ответа все используемые в шаблоне переменные ищутся в теле ответа, а не в Контексте Чата. Обращение к телу ответа происходит через переменную 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_code — 499.
  3. 3.
    Кодирование итогового URL внешнего запроса.
    1. 1.
      Система проверяет наличие недопустимых символов в итоговом URL внешнего запроса и производит их кодирование
      image.png
       В примере в Endpoint записан с недопустимыми символами — кириллицей, поэтому в Итоговый URL внешнего запроса он попадет в закодированном виде: http://example.com/%D0%B0%D0%B1%D0%B2%D0%B3%D0%B4
    2. 2.
      Если Итоговый URL внешнего запроса содержит уже закодированные части (например, параметры), система это распознает и не произведет повторной кодировки.
      image.png
       В примере в Endpoint записан уже закодированный URL, поэтому в Итоговый URL внешнего запроса он попадет без изменений в виде http://example.com/abc%253D
    3. 3.
      Если Итоговый URL внешнего запроса содержит и закодированные части и недопустимые незакодированные символы, система это распознает закодирует только недопустимые незакодированные символы
      image.png
       В примере будет закодирована только часть еюя и в Итоговый 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;
      Agent Builder _ CHATME.ai — Dialog System Technolo.png
      ​
    3. 3.
      При неуспешном выполнении, тело ответа содержит текст ошибки, полученной от внешней системы;
      Agent Builder _ CHATME.ai — Dialog System Technoloпп.png
      ​
    4. 4.
      При получении .xml от внешней системы ответ записывается строкой;
    5. 5.
      При получении от внешней системы пустого {} BODY в тело ответа записывается пустая строка.

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

При экспорте Агента происходит также экспорт всех Внешних запросов, содержащихся в его Обученной модели агента. Агент с включенными в него Внешними запросами экспортируется в виде файла формата .cfg. При импорте Агента происходит импорт используемых в нем Внешний запрос, при этом:
  1. 1.
    Если в компании есть Внешний запрос с идентичным названием и содержимым, дублирования Внешнего запроса не происходит. В импортированном Агенте будет использован уже существующий Внешний запрос. В остальных случаях будет создан новый Внешний запрос;
  2. 2.
    Если в компании есть Внешний запрос с идентичным названием, но отличающимся содержимым, будет создан дубликат этого Внешнего запроса с автоматически сгенерированным именем:
    запрос.png
    ​
  3. 3.
    Если в компании есть Внешний запрос с отличающимся названием, но идентичным содержанием, то Внешний запрос из конфига будет импортирован.
  4. 4.
    Если в компании нет такого Внешний запрос, то он будет импортирован и появится в списке Внешний запросов.
Previous
Создание и сохранение переменных контекста | Слот Memory (старый синтаксис)
Next
Распознавание сущностей | Слот Synonym
Last modified 9d ago