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

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

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

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

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

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

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

2. REQUEST* — Внешний запрос из Ресурсы Компании. Работает инкрементальный регистронезависимый поиск запроса в списке.

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

Задержка при отправке запроса

Пользователь может сконфигурировать Внешний запрос таким образом, чтобы он осуществлял Задержка отправки внешнего запроса — некоторое ожидание до отправки данного запроса. Для этого необходимо в заголовках запроса в разделе Headers указать специальный заголовок er-delayсо значением Задержка отправки внешнего запроса в секундах.Требования к значению:

• целые числа - от 0 до 60

• числа больше 60 трактуются как 60

• дробные числа, отрицательные числа и не числа трактуются как 0

Примеры:

1. заголовок er-delay отсутствует

2. соответствует ожиданию в 0 секунд

3. er-delay: 10

4. соответствует ожиданию в 10 секунд

5. er-delay: 0

6. соответствует ожиданию в 0 секунд

7. er-delay: 100500

8. соответствует ожиданию в 60 секунд

9. er-delay: -100500

10. соответствует ожиданию в 0 секунд

11. er-delay: non-integer-value

12. соответствует ожиданию в 0 секунд

Внешние запросы

Внешний запрос представляет собой объект Ресурсы Компании, то есть доступен из всех Агентов данной компании. Добавить, изменить, посмотреть или удалить запрос можно на Вкладка внешних запросов — External Requests.

Работа слота

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

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

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

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

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

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

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

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

   2. Если размер тела, получаемого в ответ на Внешний запрос, больше 5 КБ, но меньше 100 КБ, в raw_response записывается {”error”:”received body is larger than 5kb, you can parse it in External Request settings, but it will not be copied to raw_response”}

   3. Если размер тела, получаемого в ответ на Внешний запрос, превышает Лимит на размер получаемого тела в ответ на Внешний запрос , то тело заменяется на пустое.

   4. 1. В raw_response записывается: {”success”:false,”error”:”received body is too big, max 100kb allowed”}.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

          2. Вторая часть содержит тело ответа:

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

       4. если запрос к внешней системе удалось отправить, но не был получен ответ, то в raw_response записывается значение no response

   14. При получении .xml от внешней системы - ответ записывается строкой

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