Коннектор, тип universalAPI

Коннекторы с типом universalAPI используются для получения данных из любых REST API, поддерживающих ответы в формате JSON.

Коннектор этого типа предназначен для работы только с теми REST API, которые могут быть сконфигурированы средствами пользовательского интерфейса. Для таких коннекторов всегда используется нормализатор json. В рамках одного коннектора можно создать только одно соединение. В рамках одного соединения можно настроить только один URL-адрес.

Коннектор universalAPI поддерживает сбор событий только из структур JSON с одним уровнем вложенности. Если структура ответа содержит вложенные списки (например, список объектов, внутри которых находится другой список объектов), сбор событий из таких списков средствами коннектора не поддерживается. В этом случае рекомендуется собирать данные верхнего уровня, а обработку вложенных структур выполнять на уровне нормализатора.

Проверку соединения с источником можно выполнить после запуска коллектора, проанализировав его журналы. В случае возникновения проблем с соединением или авторизацией коллектор будет отображаться в разделе Ресурсы → Активные сервисы в желтом статусе.

Коннектор с типом universalAPI не заменяет собой другие существующие API-коннекторы, например, office365.

Доступные параметры коннектора с типом universalAPI описаны в таблицах ниже.

Вкладка Основные параметры

Параметр

Описание

Название

Уникальное имя ресурса. Максимальная длина имени составляет до 128 символов в кодировке Unicode.

Обязательный параметр.

Тенант

Название тенанта, которому принадлежит ресурс.

Обязательный параметр.

Тип

Тип коннектора – universalAPI.

Обязательный параметр.

Теги

Теги для поиска ресурса.

Необязательный параметр.

Описание

Описание ресурса. Максимальная длина описания составляет до 4000 символов в кодировке Unicode.

URL

URL-адрес REST API сервера. Указывать протокол подключения (http или https) не нужно. Он определяется автоматически в зависимости от значения параметра tlsMode. Вы можете указать только один URL-адрес.

Обязательный параметр.

Интервал запросов (сек.)

Интервал опросов заданного URL, в секундах. Укажите число от 60 до 3600 (то есть от 1 минуты до 60 минут). Значение по умолчанию: 3600.

HTTP метод

HTTP-метод запроса к API. Доступные значения:

  • GET.
  • POST.
  • PUT.
  • DELETE.

Обязательный параметр.

Авторизация

Способ авторизации для подключения к API. Доступны следующие способы авторизации:

  • Выключена. Авторизация не используется.
  • Обычная. Авторизация по логину и паролю. Нужно использовать секрет типа credentials.
  • Токен. Авторизация по токену. Нужно использовать секрет типа token.

Подробную информацию можно найти в разделе о секретах.

Значение по умолчанию: Выключена.

Если на вкладке Дополнительные параметры в поле Режим TLS выбрано значение Нестандартный PFX, поле Авторизация будет недоступно.

Идентификатор секрета

Поле доступно, если в поле Авторизация выбрано значение Обычная. Нужно выбрать секрет типа credentials.

Обязательный параметр.

Токен

Поле доступно, если в поле Авторизация выбрано значение Token. Нужно выбрать секрет типа token.

Обязательный параметр.

Название токена

Поле доступно, если в поле Авторизация выбрано значение Token. Доступные значения:

  • Bearer.
  • OAuth.

Вы также можете указать название вручную.

Обязательный параметр.

Тело запроса

Тело HTTP-запроса. Вы можете также использовать переменные: $token, $username, $password, $identityValue.

Если включена итерация и в состоянии есть ключ итерации, он автоматически подставляется в параметры запроса.

Путь к данным в формате JSONPath

Путь к данным в структуре ответа API, указывающий на объект или список объектов.

Путь задается в формате JSONPath (например, $.data, $.data.edges[0].node.event, $.data.edges[*].node.event). Символ $ указывать не нужно, он подставляется в поле автоматически.

Обязательный параметр.

Поле Identity

Переключатель для включения уникального идентификатора, по которому будут отбираться события. По умолчанию переключатель выключен.

Путь к полю в формате JSONPath

Поле доступно, если переключатель Поле Identity включен.

Путь к полю идентификатора в структуре элемента данных ответа API задается в формате JSONPath (например, $.id). Символ $ указывать не нужно, он подставляется в поле автоматически.

Обязательный параметр.

Тип

Поле доступно, если переключатель Поле Identity включен.

Тип поля идентификатора, по которому будут отбираться события. Доступные значения:

  • int.
  • float.
  • string.
  • date.

    Внутри системы значение хранится в виде метки времени в миллисекундах.

Обязательный параметр.

Формат даты

Поле доступно, если в поле Тип выбрано значение date.

Формат даты может содержать дату, время, доли секунды и временную зону, например, YYYY-MM-DDTHH:mm:ssX.

Заданный формат применяется:

  • Для парсинга начального значения идентификатора.
  • Для парсинга значений идентификатора из ответов REST API. Если формат даты содержит временную зону, значение обрабатывается в указанной временной зоне. Если формат даты не содержит временную зону, значение обрабатывается в UTC.
  • Для формирования строки даты для параметров запроса (например, $identityValue в queryParams, headers, body). Если формат даты содержит временную зону, строка формируется во временной зоне сервера. Если формат даты не содержит временную зону, строка формируется в UTC.

Начальное значение

Поле доступно, если переключатель Поле Identity включен.

Начальное значение поля идентификатора задается в виде строки в формате, соответствующем выбранному типу в поле Тип. Для типа date нужно указать значение в формате, указанном в поле Формат даты.

Значение может содержать символы Unicode. Минимальная длина – 1 символ.

Параметры итераций

Переключатель для включения режима итераций, используемого для API с поэтапной выдачей данных. По умолчанию переключатель выключен.

Путь к полю с ключом итерации в формате JSONPath

Путь к полю ключа итерации в структуре элемента ответа API в формате JSONPath. Символ $ подставляется в поле автоматически.

Обязательный параметр.

Интервал запросов в режиме итераций (сек.)

Интервал опроса URL в режиме итерации, в секундах.

Значение по умолчанию: 60.

Параметр URL для ключа итерации

Имя параметра URL, в котором передается ключ итерации при запросе к API.

Необязательные параметры запроса

 

Дополнительные параметры запроса в формате map[string][]string. Вы можете также использовать переменные: $token, $username, $password, $identityValue.

Для добавления параметра нажмите на кнопку + Добавить и заполните поля Ключ и Значение. Для удаления параметра установите рядом с ним флажок и нажмите на кнопку Удалить.

Заголовки запроса

Опциональные заголовки HTTP-запроса в формате map[string][]string. Вы можете также использовать переменные: $token, $username, $password, $identityValue.

Для добавления параметра нажмите на кнопку + Добавить и заполните поля Ключ и Значение. Для удаления параметра установите рядом с ним флажок и нажмите на кнопку Удалить.

Дополнительные поля

Дополнительные поля, которые добавляются в каждый элемент данных, в формате map[string][]string.

Для добавления полей нажмите на кнопку + Добавить и заполните поля Название поля и JSONPath. Для удаления поля установите рядом с ним флажок и нажмите на кнопку Удалить.

Вкладка Дополнительные параметры

Параметр

Описание

Отладка

Переключатель, включающий режим отладки для коннектора. По умолчанию выключен.

Кодировка символов

Кодировка символов. По умолчанию выбрано значение UTF-8.

Прокси-сервер

Параметры прокси-сервера, если он требуется для подключения к API. Можно выбрать один из доступных прокси или создать новый.

Режим TLS

Режим шифрования TLS. При использовании шифрования TLS вы не можете указать IP-адрес в поле URL на вкладке Основные параметры. Доступные значения:

  • Выключено – не использовать шифрование TLS. Это значение выбрано по умолчанию.
  • Включено – использовать шифрование TLS, но без верификации сертификатов.
  • Нестандартный CA – использовать шифрование TLS с верификацией сертификата, подписанного центром сертификации. При выборе этого значения в раскрывающемся списке Нестандартный CA укажите секрет с сертификатом, подписанным центром сертификации. Вы можете выбрать существующий секрет или создать новый секрет. Для создания нового секрета выберите значение Создать.

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

    Как создать сертификат, подписанный центром сертификации?

  • Нестандартный PFX – использовать шифрование TLS с PFX-секретом. Вам нужно сформировать PFX-сертификат с закрытым ключом в формате PKCS#12-контейнера, после чего загрузить PFX-сертификат в веб-интерфейс KUMA в виде PFX-секрета. При выборе этого значения в раскрывающемся списке Нестандартный PFX укажите PFX-секрет с сертификатом, подписанным центром сертификации. Вы можете выбрать существующий PFX-секрет или создать новый PFX-секрет. Для создания нового PFX-секрета выберите значение Создать.

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

    Как создать PFX-секрет?

Время ожидания запроса (сек.)

Период ожидания ответа на запрос к API, в секундах. По умолчанию время ожидания ответа составляет 30 секунд.

Количество повторных запросов

Количество повторных попыток выполнить запрос при появлении ошибки.

Значение по умолчанию: 1.

Интервал повторных запросов (сек.)

Интервал между повторными попытками запроса, в секундах.

Значение по умолчанию: 0.

В начало