Тип universalAPI
Коннекторы с типом universalAPI используются для получения данных из любых REST API, поддерживающих ответы в формате JSON.
Коннектор этого типа предназначен для работы только с теми REST API, которые могут быть сконфигурированы средствами пользовательского интерфейса. Для таких коннекторов всегда используется нормализатор json. В рамках одного коннектора можно создать только одно соединение. В рамках одного соединения можно настроить только один URL.
Коннектор universalAPI поддерживает сбор событий только из структур JSON с одним уровнем вложенности. Если структура ответа содержит вложенные списки (например, список объектов, внутри которых находится другой список объектов), сбор событий из таких списков средствами коннектора не поддерживается. В этом случае рекомендуется собирать данные верхнего уровня, а обработку вложенных структур выполнять на уровне нормализатора.
Проверку соединения с источником можно выполнить после запуска коллектора, проанализировав его журналы. В случае возникновения проблем с соединением или авторизацией коллектор будет отображаться в разделе Ресурсы и сервисы → Активные сервисы в желтом статусе.
Коннектор с типом universalAPI не заменяет собой другие существующие API-коннекторы, например, office365.
При создании этого типа коннектора вам требуется указать значения следующих параметров:
Вкладка Основные параметры:
- Название – уникальное имя ресурса. Максимальная длина имени составляет до 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-сертификат в Консоли OSMP в виде PFX-секрета. При выборе этого значения в раскрывающемся списке Нестандартный PFX укажите PFX-секрет с сертификатом, подписанным центром сертификации. Вы можете выбрать существующий PFX-секрет или создать PFX-секрет. Для создания нового PFX-секрета выберите значение Создать.
Если вы хотите изменить параметры существующего секрета, нажмите рядом с ним на значок карандаша
.
- Время ожидания запроса (сек.) – период ожидания ответа на запрос к API, в секундах. По умолчанию время ожидания ответа составляет 30 секунд.
- Количество повторных запросов – количество повторных попыток выполнить запрос при появлении ошибки. Значение по умолчанию:
1. - Интервал повторных запросов (сек.) – интервал между повторными попытками запроса, в секундах. Значение по умолчанию:
0.
