Коннекторы с типом 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 укажите секрет с сертификатом, подписанным центром сертификации. Вы можете выбрать существующий секрет или создать секрет. Для создания нового секрета выберите значение Создать.
Если вы хотите изменить параметры существующего секрета, нажмите рядом с ним на значок карандаша.
Вы можете создать сертификат, подписанный центром сертификации, на сервере Ядра KUMA (в примерах команд ниже используется OpenSSL).
Чтобы создать сертификат, подписанный центром сертификации:
Создайте ключ, который будет использоваться центром сертификации, например:
openssl genrsa -out ca.key 2048
Создайте сертификат для созданного ключа, например:
openssl req -new -x509 -days 365 -key ca.key -subj "/CN=<общее имя устройства центра сертификации>" -out ca.crt
Создайте приватный ключ и запрос на его подписание в центре сертификации, например:
openssl req -newkey rsa:2048 -nodes -keyout server.key -subj "/CN=<общее имя устройства сервера Open Single Management Platform>" -out server.csr
Создайте сертификат, подписанный центром сертификации. Вам нужно включить в переменную subjectAltName доменные имена или IP-адреса сервера, для которого вы создаете сертификат, например:
Загрузите созданный сертификат server.crt в Консоли Open Single Management Platform в секрет с типом certificate, после чего в раскрывающемся списке Нестандартный CA выберите секрет с типом certificate.
Нестандартный PFX PFX – использовать шифрование TLS с PFX-секретом. Вам нужно сформировать PFX-сертификат с закрытым ключом в формате PKCS#12-контейнера, после чего загрузить PFX-сертификат в Консоли OSMP в виде PFX-секрета. При выборе этого значения в раскрывающемся списке Нестандартный PFX укажите PFX-секрет с сертификатом, подписанным центром сертификации. Вы можете выбрать существующий PFX-секрет или создать PFX-секрет. Для создания нового PFX-секрета выберите значение Создать.
Если вы хотите изменить параметры существующего секрета, нажмите рядом с ним на значок карандаша.