15. Инструменты API
Для осуществления автоматизации работы с интерфейсом Datamart Platform Studio предоставляет доступ пользователям по Open API. Для работы с API требуется пройти аутентификацию и получить JWT-токен, который требуется указывать каждый раз при вызове методов API для авторизации в Datamart Platform Studio.
JWT-токен может быть получен пользователем, как напрямую в сервисе аутентификации keycloak, так и при помощи вызова метода auth-system в API.
Примечание
Для взаимодействия с API требуется использование аутентификации и JWT-токена, полученного в keycloak. Аутентификация методом DB и LDAP не поддерживается при использовании API.
В текущей версии Datamart Platform Studio реализованы следующие версии API:
# /api/v1/ - REST API (ограниченный функционал взаимодействия с Datamart Platform Studio, доступ к эндпоинтам инсталляций при помощи Proxy API) # /api/v2/ - REST API в формате JSON API (полный набор функций Datamart Platform Studio)
Примечание
Для примеров обращения к API в текущем разделе документации используется утилита curl, по правилам безопасности, предполагается вызов утилиты из сертифицированной версии ОС. В продакшн пользователь должен использовать любую http-утилиту, сертифицированную ФСТЭК или соответствующую требованиям безопасности, установленным для эксплуатации Системы.
15.1. Open API документация
Описание функций в формате Open API генерируется автоматически и выводится в веб-интерфейсе Datamart Platform Studio программой Swagger по адресу:
http(s)://<URL |prod|>:8088/api-docs/index.html
В заголовке можно выбрать версию API по которой отобразит документацию swagger (v1 или v2):
Рисунок 15.1 Документация по API
Ссылки на документацию по API из интерфейса Datamart Platform Studio отображаются в правом нижнем углу:
Рисунок 15.2 Ссылка на документацию по API из веб-интерфейса Datamart Platform Studio
15.2. Аутентификация
Получить токен аутентификации пользователя для авторизации в Datamart Platform Studio можно несколькими способами:
Запросом к API сервиса аутентификации Keycloak;
В веб-интерфейсе сервиса аутентификации пользователь может запросить токен;
Запросом к API v1 Datamart Platform Studio с передачей логина и пароля в параметрах запроса (метод deprecated, не рекомендуется к использованию);
Запросом к API v2 Datamart Platform Studio с передачей логина и пароля в зашифрованном теле запроса;
Примечание
При работе Datamart Platform Studio в режиме атентификации AUTH=IAM JWT-токен генерируется и валидируется в Keycloak, при работе в режимах AUTH=DATABASE или AUTH=LDAP WT-токен генерируется и валидируется в Datamart Platform Studio. Настройка режима атентификации выполняется в переменных окружения и требует перезапуска экземпляра Datamart Platform Studio для вступления в силу.
15.2.1. Получение токена по API от сервиса аутентификации
При наличии доступа к сервису аутентификации получить JWT-токен можно напрямую от сервиса при помощи запроса к API IAM сервиса аутентификации Keycloak. Пример curl-запроса:
curl --location 'https://<iam-server>/realms/<realm>/protocol/openid-connect/token'
--header 'Content-Type: application/x-www-form-urlencoded'
--data-urlencode 'username=<username>'
--data-urlencode 'password=<password>'
--data-urlencode 'client_id=<clientid>'
--data-urlencode 'grant_type=password'
--data-urlencode 'scope=openid'
где:
<iam-server> — ip-адрес или hostname сервера IAM;
<clientid> — имя клиента IAM;
<realm> — realm клиента в IAM;
<username> — имя пользователя IAM;
<password> — пароль пользователя IAM;
15.2.2. Получение токена в веб-интерфейсе сервиса аутентификации
В интерфейсе Keycloak в разделе Credentials в карточке пользователя также возможно получение токена:
Рисунок 15.3 Получение токена в интерфейсе Keycloak
15.2.3. Аутентификация и получение токена при помощи API v1 (deprecated)
Интерфейс аутентификации в API реализован в эндпоинте: /api/v1/auth-system/
Получить токен можно запросом:
curl -X POST \
'http://<ip-studio>:8088/api/v1/auth_system' \
-d "username=<username>" \
-d "password=<password>" \
-d "organization_ogrn=<organization_ogrn>" \
-d "datamart_mnemonic=<datamart_mnemonic>"
где:
<ip-studio> — ip-адрес Студии;
<username> — имя пользователя IAM;
<password> — пароль пользователя IAM;
<organization_ogrn> — ОГРН Организации, в рамках которой развёрнута Витрина;
<datamart_mnemonic> — мнемоника целевой Витрины.
Примечание
Важно обратить внимание на протокол запроса. Если он будет некорректным (например, http вместо https), то ответ сервера будет содержать ошибку с кодом 500 - Internal Server Error.
Пример успешного ответа Datamart Platform Studio на запрос токена:
{
"access_token": "eyJhbGc<...>ZMF4UA",
"expires_in": 3600,
"refresh_expires_in": 3600,
"refresh_token": "eyJhb<...>fY-2M",
"token_type": "Bearer",
"id_token": "eyJhbGc<...>i3Jow",
"not-before-policy": 0,
"session_state": "e0a422ed-a441-43cc-a011-533bcdb5798d",
"scope": "openid email"
}
Пример ответа Datamart Platform Studio в случае возврата ошибки Keycloak на запрос токена (в текущем примере истек срок действия аккаунта пользователя Keycloak):
{
"message": "Keycloak connection error"
"errors":["invalid_grant - Account is not fully set up"]
}
Примечание
Если пользователь заведен в Keycloak, но не проходил авторизацию через веб-интерфейс Datamart Platform Studio, то запись об аккаунте пользователя отсутствует в Datamart Platform Studio. При первом запросе токена будет создан аккаунт пользователя в Datamart Platform Studio, если запрос успешный.
Перед отправкой JWT Datamart Platform Studio проверяет соответствие ОГРН организации из запроса, списку организаций имеющих доступ в Datamart Platform Studio, а также наличие услуги с указанной datamart_mnemonic у этой организации.
Если проверки не пройдены, то в body возвращается текст ошибки:
{
"error": "У данной учетной записи отсутствует заявленная организация по ОГРН #{organization_ogrn}"
}
{
"error": "У организации данной учетной записи отсутствует витрина с мнемоникой #{datamart_mnemonic}"
}
15.2.4. Аутентификация и получение токена при помощи API v2
Метод: POST /api/v2/auth_system
Body Request :
{
"data":{
"type":"auth",
"attributes":{
"username": "string",
"password": "string",
"refresh_token": "string",
"auth_protocol": "string",
"organization_ogrn": "string",
"datamart_mnemonic": "string",
"environment": "string",
"auth_service_id": "string",
"grant_type": "string"
}
}
}
где:
username - Имя пользователя (при grant_type=password)
password string - Пароль пользователя (при grant_type=password)
refresh_token - Рефреш токен (при grant_type=refresh_token)
auth_protocol - Протокол аутентификации (DB, LDAP, OAuth (= IAM)
organization_ogrn - ОГРН организации
datamart_mnemonic - Мнемоника услуги
environment - Окружение услуги (development, staging, test, production)
auth_service_id - Идентификатор auth-сервиса (не обязательно)
grant_type - Тип авторизации (password, refresh_token)
Пример содержимого body запроса токена по паролю:
{
"data":{
"type":"auth",
"attributes":{
"username": "test_user",
"password": "password",
"auth_protocol": "OAuth",
"organization_ogrn": "12345678901",
"datamart_mnemonic": "123",
"grant_type": "password"
}
}
}
Пример содержимого body запроса токена по рефреш-токену:
{
"data":{
"type":"auth",
"attributes":{
"refresh_token": "eyJhbGc<...>qhM",
"auth_protocol": "OAuth",
"organization_ogrn": "12345678901",
"datamart_mnemonic": "123",
"environment": "production",
"grant_type": "refresh_token"
}
}
}
В случае, когда в Datamart Platform Studio настроено подключение к нескольким сервисам аутентификации, может потребоваться обращение к конкретному сервису. В этом случае, в запросе надо указать требуемый auth_service_id, например:
{
"data":{
"type":"auth",
"attributes":{
"username": "test_user",
"password": "password",
"auth_protocol": "IAM",
"auth_service_id": "12",
"grant_type": "password"
}
}
}
Ответ Body Response:
{
"data":{
"type":"user",
"id":"123",
"attributes":{
"auth_data":{
"access_token": "string",
"expires_in": "integer",
"refresh_expires_in": "integer",
"refresh_token": "string",
"token_type": "string",
"id_token": "string",
"not-before-policy": "integer",
"session_state": "string",
"scope": "string"
}
}
}
}
Пример ответа
{
"data":{
"type":"user",
"id":"123",
"attributes":{
"auth_data": {
"access_token": "eyJhb<...>M71A",
"expires_in": 3600,
"refresh_expires_in": 3600,
"refresh_token": "eyJhbG<...>zqhM",
"token_type": "Bearer",
"id_token": "eyJhbG<...>XuzA",
"not-before-policy": 0,
"session_state": "7bd4b8b5-21c7-4e95-b327-4ee6cb34c99d",
"scope": "openid email"
}
}
}
}
Свойства Body Response:
type - Тип объекта (user)
id - Идентификатор пользователя
- attributes - Атрибуты ответа
- auth_data - Данные аутентификации
access_token - Аутентификационный токен
expires_in - Период жизни токена
refresh_expires_in - Период обновления токена
refresh_token - Refresh токен
token_type - Тип токена
id_token - ID токена
not-before-policy - Not before policy
session_state - Session state
scope - Сфера применения токена
Возвращаемые коды ошибок:
400 - Неверный запрос
401 - Ошибка аутентификации
403 - Доступ запрещен
422 - Некорректные параметры запроса
500 - Ошибка сервера
15.3. Примеры использования методов API v1
15.3.1. Проверка healthcheck
Проверка состояния экземпляра Datamart Platform Studio:
http(s)://<URL |prod|>:8088/api/v1/healthcheck
Ответ возвращается в формате JSON и содержит статус Datamart Platform Studio, окружения, БД и информацию о выполнении миграций последнего обновления.
Пример содержимого ответа:
{
"code":200,
"status":
{
"database":"OK",
"migrations":"OK",
"data_migrations":"OK"
},
"info":
{
"env":"production",
"root":"/app",
"booted_at":"2023-08-18T16:52:05+00:00"
}
}
15.4. Использование методов API v2 (JSON API)
Основное отличие API v2 от v1 состоит в расширении функционала API и использовании соглашения JSON API в v2.
В ответах GET-запросов содержится json со всеми данными объекта, а также ссылками на ID связанных объектов (в разделе relationship).
Рассмотрим пример обращения к эндпоинту /api/v2/data_centers/ для получения информации о дата-центре:
Рисунок 15.4 Пример запроса к API v2 на получение информации о дата-центре
15.4.1. Отображение информации по связанным объектам
JSON API позволяет отобразить в ответах не только информацию по текущему объекту, но и по связанным.
Для включения в ответ API данных по связанным объектам требуется использовать параметр «include» с указанием типа объекта. Рассмотрим пример обращения к эндпоинту /api/v2/data_centers/ для получения информации о дата-центре с включением в ответ данных о связанной с ДЦ организацией:
Рисунок 15.5 Пример запроса к API v2 на получение информации о ДЦ и связанной с ДЦ организацией
15.4.2. Ограничение вывода атрибутов
При получении списка каких-либо сущностей можно ограничить набор возвращаемых полей в attributes и relationships. Таким образом если указать параметр fields, то будут выводиться только указанные поля.
Синтаксис: fields[<таблица>]=<колонка>
/api/v2/data_centers?fields[data_centers]=cpu,ram
Если используется вывод связанных сущностей через include, то можно и для них ввести ограничения по выводу атрибутов.
/api/v2/data_centers?include=organization&fields[organizations]=name
15.4.3. Пагинация
Пример:
/api/v2/data_centers?page[page]=2&page[limit]=1
Параметры:
page[limit] - количество элементов на странице
page[page] - номер страницы
В ответе каждого эдпоинта-листинга («GET /data_centers», «GET /organizations» и т.д.) присутствует блок links, в котором есть ссылки на первую, предыдущую, следующую и последнюю страницы, если таковые имеются:
{
"data": [...],
"links": {
"first": "/api/v1/data_centers?page%5Blimit%5D=1",
"previous": "/api/v1/data_centers?page%5Bpage%5D=1&page%5Blimit%5D=1",
"next": "/api/v1/data_centers?page%5Bpage%5D=3&page%5Blimit%5D=1",
"last": "/api/v1/data_centers?page%5Bpage%5D=36&page%5Blimit%5D=1"
}
}
15.4.4. Сортировка
Параметр sort
Параметр для сортировки результатов по атрибутам модели.
Синтаксис:
Один атрибут: sort=<атрибут>
По убыванию: sort=-<атрибут> (символ минус перед атрибутом)
Несколько атрибутов: sort=<атрибут_1>,-<атрибут_2>,<атрибут_3> (через запятую)
По атрибуту ассоциации: sort=<ассоциация>_<атрибут> (нижнее подчеркивание для вложенных атрибутов)
Сортировка по убыванию атрибута servers_count записей из таблицы data_centers:
/api/v2/data_centers?sort=-servers_count
Двойная сортировка – по возрастанию servers_count, затем по возрастанию id:
/api/v2/data_centers?sort=servers_count,id
Сортировка дата-центров по наименованию организации:
/api/v2/data_centers?sort=organization_title
15.4.5. Фильтрация
Используется параметр filter[]. В квадратных скобках – атрибут и «предикат», значение – искомая строка.
Предикаты в поисковых запросах определяют метод сопоставления данных. Например, предикат cont проверяет, содержит ли атрибут title искомое значение.
/api/v2/data_centers?filter[title_cont]=цод
С полным списком предикатов и их описанием можно ознакомиться на странице библиотеки Ransack отвечающей за поиск:
Наиболее часто используемые:
_cont – содержит ли значение? Например, найти записи, содержащие в своем названии строку «test»:
filter[title_cont]=test
_eq – точно совпадает со значением? Например, найти записи, со статусом «installed»:
filter[status_eq]=installed
_in – принимает одно из значений? Например, найти записи, статус которых или «installed» или «stopped»:
filter[status_in][]=installed&filter[status_in][]=stopped
_true или _false – для булевых атрибутов. Например, найти активные и не заблокированные записи:
filter[active_true]=1&filter[locked_false]=1
_present или _blank – существует ли / пусто ли? Например, найти записи, у которых колонка payload не null и не пустая строка:
filter[payload_present]=1
15.4.5.1. Фильтрация по атрибутам ассоциаций
Дата-центр принадлежит Организации (таблица organizations) и Гипервизору (таблица hv_platforms). А Гипервизор в свою очередь принадлежит Типу Гипервизора (таблица hv_types). Поэтому можно искать записи по атрибутам из этих таблиц. Для этого мы используем синтаксис <связь>_<атрибут>_<предикат>. В случае иерархии связей, мы используем подчеркивания для разделения уровней.
Например, найти Дата-центры, принадлежащие Организациям содержащим в названии строку «акционерное»:
/api/v2/data_centers?filter[organization_title_cont]=акционерное
Или найти Дата-центры, принадлежащие Гипервизору с Типом «bazis»:
/api/v2/data_centers?filter[hv_platform_hv_type_name_eq]=bazis
15.4.6. Список разделов API v2
Ниже приводится список разделов методов API v2. Подробное описание каждого метода находится в swagger-документации в интерфейсе Datamart Platform Studio.
Аутентификация (Auth systems)
- Управление сущностями платформы (Core Entities)
Приложения (Apps)
Пакеты (Bundles)
Кластеры (Clusters)
Услуги (Datamarts)
Профили услуг (Datamart profiles)
Центры обработки данных (Data centers)
Установки (Installations)
Организации (Organizations)
Репозитории (Repositories)
Хранилища репозиториев (Rephubs)
Серверы (Servers)
Типы услуг (Service types)
- Конфигурация и свойства (Configuration)
Глобальные свойства (Global Properties)
Свойства (Properties)
Интерфейсы (Interfaces)
- Задачи и задания (Tasks & Jobs)
Группы задач (Task groups)
Задачи (Tasks)
Фоновые задания (Jobs)
Очереди (Queues)
- Вспомогательные сервисы (Auxiliary)
Загружаемые файлы (Uploaded files)
Пользователи (Users)
Информация о студии (Studio)