Вкладка внешних запросов — External Requests

Вкладка EXTERNAL REQUESTS — вкладка, на которой создаются Внешний запрос для дальнейшего их использования в Агентах Компания.

Переход на вкладку Внешних запросов

1. В список Внешний запрос Компания можно перейти двумя способами:

2. 1. перейти на вкладку Resourses (Вкладка ресурсов Компании — Resourses) и нажать кнопку External Requests;

   2. перейти в БотБилдер Агента и открыть вкладку External Requests.

Список Внешних запросов

На вкладке Внешний запрос представлен список всех Внешний запрос Компания:

1. Name — названия Внешний запросов;

2. Кнопка сортировки Внешний запросов по алфавиту;

3. 1. По нажатию кнопки сортировка Внешний запросов меняется: от начала алфавита к концу и наоборот.

4. Method and URL — URL назначения, куда должен быть отправлен запрос и метод HTTP запроса;

5. In use — использование Внешний запросов в Агентах;

6. 1. Напротив каждого Внешний запроса, используемого в Агентах, проставлена галочка и кнопка Clarify;

   2. По нажатию кнопки Clarify выводятся иконки Агентов, в которых используется Внешний запрос.

Поиск по Внешним запросам

Поиск по имени Внешнего запроса

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

Поиск по использованию Внешнего запроса

Поиск по использованию Внешний запроса в Агентах производится с помощью фильтров In use и Not in use.

1. По нажатию на кнопку In use выводятся Внешний запросы, используемые в Агентах;
2. По нажатию на кнопку In use вместо фильтра Not in use выводится фильтр Agent — фильтр по Агентам.
3. 1. По нажатию на кнопку Agent открывается панель поиска по Агентам.
   2. Чтобы найти Внешний запросы, которые используются в определенных Агентах, необходимо кликнуть по необходимым Агентам в списке.
4. По нажатию на кнопку Not in use выводятся Внешний запросы, не используемые в Агентах.

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

Создание Внешнего запроса

Чтобы создать Внешний запросы, необходимо:

1. Перейти в список Внешний запросов.
2. Нажать кнопку Create new.
3. По нажатию кнопки на панели справа откроется форма создания нового Внешний запроса.
4. Необходимо заполнить поля на вкладках формы создания Внешний запроса.

Вкладка Main

Вкладка Main содержит базовые данные Внешний запроса.Поля вкладки:

1. Name* — название Внешний запрос. Максимальная длина значения поля — 1000 символов.
2. Description — описание Внешний запрос. Максимальная длина значения поля — 1000 символов.
3. Метод запроса* — HTTP метод для данного запроса. По умолчанию установлен метод GET.

4. 1. GET

   2. POST

   3. PUT

   4. PATCH

   5. DELETE

   6. HEAD

5. Endpoint* — адрес вебхука, на который будет отправлен данный Внешний запрос. Максимальная длина значения поля — 1000 символов.
6. 1. Формат значения:

   2. 1. Строка
      2. Контекстная переменная в формате {{ var }}
      3. Выражение или Выражение с управляющей конструкцией. Подробнее: Использование синтаксиса в External Request.

Вкладка Headers

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

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

2. Value* — значение заголовка. Максимальная длина значения поля — 10000 символов.

3. 1. Формат значения: допустимо использование Выражение или Выражение с управляющей конструкцией.
4. Кнопка крестика удаляет заголовок (строку).

5. Add new field — кнопка добавления нового заголовка.

Вкладка Query parameters

На вкладке Query parameters можно прописать параметры, которые будут подставлены к URL запроса.Поля и кнопки вкладки:

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

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

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

3. Value* — значение параметра. Максимальная длина значения поля — 10000 символов.

4. 1. Формат значения: допустимо использование Выражение или Выражение с управляющей конструкцией.
   2. Кодировка символов не латинского алфавита: Допускаются пробелы, спецсимволы и не латинский символы, будет произведено кодирование значение параметра при выполнении запроса.

   3. 1. Пример:
      2. Такой параметр будет включен в Итоговый URL внешнего запроса в виде query=%D0%B0%D0%B1%D0%B2%D0%B3%D0%B4
      3. Важно: Параметры запроса (имена и значения) будут закодированы в любом случае при подстановке в Итоговый URL внешнего запроса, во избежание двойной кодировки на вкладке Query parameters стоит указывать параметры в незакодированном виде.

5. Кнопка крестика удаляет параметр (строку).

6. Add new field — кнопка добавления нового параметра.

Вкладка Data

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

1. Data type — формат отправляемых данных (BODY в Request):

2. 1. Формат по умолчанию: JSON

   2. Форматы:

   3. 1. JSON

      2. XML

   4. Важно: при выборе формата не забывать указывать соответствующий заголовок content-type: application/json или content-type: application/xml

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

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

   2. 1. При Data type: JSON

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

      3. При Data type: XML

      4. 1. синтаксис XML

         2. регистр тегов имеет значение — <var></Var> будет считаться незакрытым тегом и запрос не будет выполнен

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

   4. 

   5. Рекомендуется использовать двойные кавычки, так как это стандарт JSON

   6. Подстановка Контекстная переменная, Выражение и Выражение с управляющей конструкцией:
   7. 1. В шаблон тела запроса можно указывать Контекстная переменная в формате {{ var }}, Выражение и Выражение с управляющей конструкцией, значения и результаты выполнения которых будут подставлены при выполнении запроса. Подробнее: Использование синтаксиса в External Request.
      2. 1. Если Контекстная переменная не удалось найти в Контекст Чата, будет подставлено пустое значение.
         2. Если при вычисление результата Выражение или Выражение с управляющей конструкцией происходит ошибка (например, при делении на 0), то Внешний запрос не будет отправлен, и в Контекст Чата будут записаны следующие Контекстная переменная:
         3. 1. error = "Template rendering (request options) error occurred."
            2. request_success = False
            3. response_status_code = 499
            4. raw_response = ""
      3. Примеры:

      4. 1. при Data type: JSON:
         2. при Data type: XML:
   8. Формат значений Контекстная переменная:
   9. 1. при Data type: JSON:

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

         2. Например, если в Сценарий агента в переменную {{ phone }} записана строка ‘89222203909’, то
         3. - при выполнении запроса с Data { “phone_num”: {{ phone }} } будет отправлено тело { “phone_num”: 89222203909 }

         4. - при выполнении запроса с Data { “phone_num”: “{{ phone }}” } будет отправлено тело { “phone_num”: “89222203909” }

      3. при Data type: XML:

      4. 1. переменная должны быть записана в XML тег с помощью фигурных скобок {{ }} и с учетом регистра. Например:
   10. Кодировка символов не латинского алфавита:

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

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

       3. Результат запроса, Data type: XML, и в client_message записана кириллица

Вкладка Response

На вкладке Response настраивается парсинг ответов на Внешний запрос в Пользовательские контекстные переменные.Парсинг выполняется в процессе обработки ответа на Внешний запрос.При парсинге ответа на запрос переменные, указанные в поле Value, не являются Контекстная переменная, а являются обращениями к объектам body и headers — частям ответа на запрос — и их свойствам.Поля и кнопки вкладки:

1. Data type — формат принимаемых данных (BODY из Response)

2. 1. Формат по умолчанию: JSON

   2. Форматы:

   3. 1. JSON

      2. XML

      3. TEXT
3. Табличная часть — массив пар Variable - Value для парсинга данных из тела и заголовков ответа на Внешний запрос в Пользовательские контекстные переменные для последующего использования их в Сценарий агента.
4. 1. Variable — название Пользовательские контекстные переменные, в которую будет записано значение. Максимальная длина значения поля — 128 символов. Имя Пользовательские контекстные переменные должно соответствовать требованиям к названию пользовательских контекстных переменных.
   2. Value — ключ или Xpath путь к тегу xml из тела или заголовков ответа, значение которого будет записано в Variable. Максимальная длина значения поля — 10000 символов. По достижении максимального значения далее символы не вводятся в поле;

   3. 1. Возможен парсинг из тела и заголовков ответа:

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

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

      3. Формат значения: допустимо использование Выражение или Выражение с управляющей конструкцией.
      4. Важно: обращение к ключу объекта, если его имя совпадает с именем Зарезервированные методы объектов происходит через квадратные скобки и кавычки.

      5. Пример: {{ data["keys"] }}

   4. Кнопка крестика: удаляет пару (строку)

   5. Add new field — кнопка добавления новой пары Variable - Value.

Важно: реализовано ограничение на размер получаемого в ответ на Внешний запрос тела: если размер тела превышает Лимит на размер получаемого тела в ответ на Внешний запрос , то оно заменяется на пустое {}. )

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

• Пример тела JSON и парсинга его в настройках слота

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

• Пример тела XML и парсинга его в настройках слота

• Пример тела TEXT и парсинга его в настройках слота

• • Для типа TEXT возможен парсинг только всего тела ответа на Внешний запрос.

Вкладка Test

На вкладке Test можно протестировать работу Внешний запрос.При создании нового Внешний запрос до заполнения параметров Внешний запрос поле cURL не заполнено.При открытии существующего Внешний запрос cURL генерируется автоматически и вкладка заполнена.Поля и элементы вкладки:

1. Refresh cURL — кнопка, по нажатию которой обновляется запрос в поле cURL на вкладке Request в соответствии с настройками Внешний запрос.
2. Test cURL — кнопка, по нажатию которой сформированный в поле cURL запрос отправляется во внешнюю систему.

3. Отображение статуса запроса — полученный после отправки запроса ответ отображается слева от кнопки перехода на вкладку Request. Цвет светофора зависит от типа полученного статуса:

4. 1. Успешный статус: 200 OK — зеленый цвет;
   2. Статусы с предупреждениями: от 201 до 399 — желтый цвет;
   3. Ошибки: от 400 и выше — красный цвет.
5. Раздел Request — раздел содержит данные для тестирования Внешний запрос.
6. 1. cURL — сгенерированный из настроек Внешний запрос cURL.
   2. Update request from cURL — кнопка, по нажатию которой обновляются поля Внешний запрос из cURL.
   3. 1. По нажатию кнопки появляется модальное окно подтверждения действия:
      2. 1. Чтобы подтвердить действие, необходимо нажать кнопку YES. При этом происходит валидация cURL:

         2. 1. при отсутствии Endpoint или некорректной структуре cURL будет выведена ошибка Invalid cURL и всплывающее уведомление Could’t parse cURL, request settings have not been updated.
            2. при корректном cURL произойдет обновление настроек Внешний запрос, а именно: поля на вкладках Headers, Query Parameters, Data Внешний запрос очищаются, и в них подставляется новая информация из cURL, в т.ч. существующие данные могут быть заменены на пустые значения, если их нет в cURL. Например, если во Внешний запрос есть заголовки, а в поле cURL заголовков нет, то при нажатии Update Request from cURL текущие заголовки из Внешний запрос будут удалены, и на их месте ничего не появится.
7. Раздел Response — раздел содержит ответ внешней системы на запрос.
8. 1. До нажатия кнопки Test cURL раздел недоступен для открытия (так как тестовый запрос не был отправлен и никакого ответа еще нет)
   2. Подраздел Body — подраздел содержит тело ответа на запрос;
   3. Подраздел Headers — подраздел содержит заголовки ответа на запрос;
   4. Отображение статуса запроса;
   5. Время от отправки запроса до получения ответа в миллисекундах;
   6. Размер тела ответа в байтах.

Добавление кастомных сертификатов к Внешнему запросу

На данный момент добавление сертификатов безопасности к Внешний запросам реализуется через поддержку: напишите на адрес [e-mail], указав идентификаторы Внешний запроса или Агента, к Внешний запросам которого необходимо подставить кастомные сертификаты, и предоставить данные сертификаты.

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

Во Внешний запрос допустимо использование Выражение и Выражение с управляющей конструкцией в полях Endpoint, 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.

Удаление Внешнего запроса

Для удаления единичного Внешний запрос необходимо:

1. Перейти в список Внешний запрос.
2. Нажать на название Внешний запрос или галочку в селекторе напротив.
3. Нажать на кнопку Delete request или Delete на панели справа;
4. Подтвердить действие в модальном окне, нажав кнопку DELETE REQUEST.
5. 1. Если удаляемый Внешний запрос используется в Агентах, при удалении появится предупреждение о том, что необходимо сначала удалить его из Сценарий агента Агента;

Клонирование Внешнего запроса

Для создания копии — клонирования единичного Внешний запроса необходимо:

1. Перейти в список Внешний запросов.
2. Нажать на название Внешний запроса или галочку в селекторе напротив.
3. Нажать на кнопку Duplicate request или Delete на панели справа;
4. Подтвердить действие в модальном окне, нажав кнопку YES, I’M SURE.

5. 
6. По нажатию кнопки YES, I’M SURE будет создана копия Внешний запроса с названием <имя клонируемого запроса >CLONE.

Массовые действия с Внешними запросами

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

Множественный выбор

Множественный выбор Внешний запросов можно осуществить следующими способами:

1. Проставить галочки в соответствующих необходимым Внешний запросам селекторах вручную.
2. 
3. Проставить галочки в селекторе массового выбора — в этом случае будут выделены все Внешний запросы на странице.
4. 
5. Выбрать одну из групп Внешний запросов. По клику на стрелочке открывается выпадающий список;
6. 
7. 1. В выпадающем списке необходимо выбрать группу Внешний запросов на текущей странице:
   2. 
   3. 1. All — все Внешний запросы;
      2. In use — только используемые в Агентах Внешний запросы;
      3. Not in use — только неиспользуемые Внешний запросы.

Снятие выделения с Внешних запросов

Снятие выделения с выбранных Внешний запросов можно осуществить следующими способами:

1. Удалить галочек из селекторов вручную.

2. Через селектор массового выбора.

3. 
4. Выбрать вариант Clear selection в выпадающем списке:

5. 

Массовое удаление Внешних запросов

Чтобы единовременно удалить несколько Внешний запросов, необходимо:

1. Выбрать несколько Внешний запросов, как описано в пункте Множественный выбор;
2. Нажать кнопку Delete requests;

3. 
4. Подтвердить действие в модальном окне, нажав кнопку DELETE REQUESTS;

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

Массовое клонирование Внешних запросов

Чтобы единовременно клонировать несколько Внешний запросов, необходимо:

1. Выбрать несколько Внешний запросов, как описано в пункте Множественный выбор;
2. Нажать кнопку Duplicate requests;
3. Подтвердить действие в модальном окне, нажав кнопку YES, I’M SURE в модальном окне.
4. По нажатию кнопки YES, I’M SURE будут созданы копии Внешний запроса с названием <название клонируемого запроса> CLONE.

Экспорт-импорт Внешних запросов при экспорте-импорте Агента

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

1. Если в Компания есть Внешний запрос с идентичным названием и содержимым, дублирования Внешний запроса не происходит. В импортированном Агенте будет использован уже существующий Внешний запрос. В остальных случаях будет создан новый Внешний запрос.
2. Если в компании есть Внешний запрос с идентичным названием, но отличающимся содержимым, будет создан дубликат этого Внешний запрос с автоматически сгенерированным именем:
3. Шаблон имени импортированного Внешний запроса: название_запроса [imported timestamp], где timestamp — время импортирования данного Агента: количество секунд с 1 января 1970 года.
4. Если в Компания есть Внешний запрос с отличающимся названием, но идентичным содержанием, то Внешний запрос из конфигурационного файла Агента будет импортирован.
5. Если в Компания нет такого Внешний запроса, то он будет импортирован и появится в списке Внешний запросов.