API
Arenadata Catalog поддерживает REST API для получения метаданных из системы, и загрузки метаданных в систему. API-интерфейсы создаются с использованием общих рекомендаций по проектированию REST API. Мы используем подход, ориентированный на схему, определяя типы и сущности в JSON схеме. На основе этих схем мы реализуем API.
Перечень всех запросов находится внутри системы, чтобы его открыть, кликните по иконке вопроса в хедере приложения и выберите раздел API.

Обзор каталога данных

Если у вас настроено подключение к системе, вы можете открыть swagger, используя ссылку: . . ./swagger.html
Для URI ресурсов соблюдаются следующие соглашения REST API:

  • Операции для сущностей доступны через URI ресурса в виде …/api/<версия>/entities.
  • Множественное число имени сущности используется в качестве имени коллекции — пример …/api/v1/users.
  • В конце конечной точки не используется косая черта (слэш). Пример использования …/api/v1/databases вместо …/api/v1/databases/.
  • URI ресурса для сущности по идентификатору- …/api/v1/entities/{id}.
  • URI ресурса для сущности по имени- …/api/v1/entities/name/{name}.
Представление ресурсов
  • Вызовы REST API возвращают ответ JSON Content-Type и Content-Length, включая длину ответа.
  • Все ответы включают поле Resource ID, даже если идентификатор был указан в запросе, чтобы упростить получение ответа клиентом.
  • Имена сущностей и полей используют camelCase в соответствии с соглашением об именовании Javascript.
  • Все ресурсы включают атрибут href с URI. Все поля взаимосвязи объекта также будут содержать ссылки href на соответствующий ресурс для легкого доступа.
  • Неизвестные поля, отправленные клиентом в запросах API, не игнорируются, чтобы гарантировать, что данные, отправленные клиентом, не будут удалены на сервере без ведома пользователя.
Конечные точки API источников данных поддерживают операции, связанные с объектами активов данных:

  • .../api/v1/databases
  • ...api/v1/tables
  • .../api/v1/metrics
  • .../api/v1/dashboards
  • .../api/v1/reports
  • .../api/v1/pipelines
  • .../api/v1/topics


Конечные точки API служб поддерживают операции, связанные со службами, из которых собираются метаданные:

  • .../api/v1/services — все ресурсы, добавленные в ADC
  • .../api/v1/services/databaseService — API, связанные со службами баз данных. Это включает транзакционные базы данных и хранилища данных
  • .../api/v1/services/dashboardService — API, связанные с дашбордами
  • ..../api/v1/services/messaingService — APIs связанные с сервисами очередей сообщений


Пользователи и команды:

  • .../api/v1/teams — APIs, связанные с командами
  • .../api/v1/users — APIs, связанные с пользователями


API поиска и предложения - эти конечные точки поддерживают API поиска и предложения:

  • .../api/v1/search — APIs поиска
  • .../api/v1/search/query — поиск объектов с использованием запроса
  • .../api/v1/search/suggest — получить предлагаемые объекты, используемые для автозаполнения


Другие APIs:

  • .../api/v1/tags — категории тегов и теги
  • .../api/v1/feeds — информация ленты активности
  • .../api/v1/usage — информация об использовании объектов
Примечания по внедрению
Мы используем Java-фреймворк Dropwizard для разработки веб-сервисов Restful. API документируются с использованием Swagger / OpenAPI 3.x. Мы используем подход schema first и определяем объекты метаданных и типы в спецификации схемы JSON версии Draft-07- 2019−09. Код Java генерируется из схемы JSON с помощью инструмента JSONschema2pojo, а код Python генерируется с помощью инструмента Data model code generator.
Боты Arenadata Catalog
В ADC существуют технические пользователи- боты. Они используются для операций выполняемых через API.

По умолчанию создан ingestion-bot- он используется для загрузки метаданных из источников в систему. Его невозможно удалить.

Вы можете создать дополнительных ботов, с помощью которых выполнять API-запросы. У каждого бота есть свой JWT-токен, который используются для авторизации при выполнении запросов. Полномочия ботов регулируются идентично ролевой модели пользователей. Соответственно, вы можете ограничивать доступ через API для каждого JWT-токена.

При создании бота вы можете указать срок хранения JWT-токена, в соответствии с политиками безопасности вашей организации.

Чтобы создать бота, выполните следующие шаги:

  1. Авторизуйтесь в системе
  2. Перейдите в раздел Настройки.
  3. В левом боковом меню выберите раздел Боты.
  4. Кликните на кнопку в правом верхнем углу страницы Добавить бота.
  5. Введите параметры бота:
  • Email
  • Наименование
  • Метод аутентификации
  • Срок действия JWT-токена
  • Описание бота
6. Нажмите кнопку Создать.

Как создать бота

После создания назначьте для бота необходимые роли.

Для просмотра JWT-токена перейдите в карточку бота, кликнув по его наименованию.
Elasticsearch
Elasticsearch- поисковая система, используемая для индексации объектов. Вы можете отслеживать журнал процесса индексации в разделе Поиск в Настройках. В случае если какие-то объекты были восстановлены, удалены, созданы, требуется выполнить переиндексацию. Для этого в разделе Elasticsearch кликните на кнопку Переиндексировать все, укажите необходимые типы объектов для переиндексацию и запустите процесс.

Как выполнить переиндексацию

Чтобы не выполнять этот процесс каждый раз вручную, настройте расписание для переиндексации. Для этого перейдите в раздел настроек Arenadata Catalog-Поиск в Настройках, кликните на ADC и добавьте загрузку с типом ElasticSearchReindex. В соответствии с настройками вашей системы укажите параметры реиндексации, сертификаты и правила доступа учетных записей.

Как настроить расписание для переиндексации

Классификаторы
В Arenadata Catalog доступно полное управление классификаторами в системе. С их помощью можно быстрее находить объекты, определять их к какому-то признаку или группе, а также управлять доступом пользователей, в зависимости от присвоенных объекту классификаторов.

Наборы классификаторов "Tier", "ПерсональныеДанные", "Персональные идентификаторы" являются системными, их невозможно удалить, но можно расширить эти наборы своими дополнениями.

Вы можете использовать условия из таблицы ниже при создании новых политик прав доступа. С помощью этих условий пользователям будет предоставлен или ограничен доступ в зависимости от присвоенного классификатора.

В условии необходимо использовать FQN классификатора, который собирается из "Набор Классификаторов.Наименование классификатора". Например, "Домены.Склады"
Создание набора классификаторов
Чтобы создать новый набор перейдите в раздел Классификаторы в основном меню приложения и нажмите кнопку Добавить сущность.
Далее Вам будет необходимо заполнить поля: Наименование, Полное наименование, Описание и параметр "Взаимоисключающий".

Параметр "Взаимоисключающий" означает, что каждому объекту может быть присвоен только один классификатор из набора. Например, только один уровень бизнес-критичности.

Создание набора классификаторов

После создания набора, вы можете наполнить его нужными классификаторами. Для этого нажмите Добавить сущность внутри конкретного набора. Для каждого классификатора необходимо заполнить: Наименование, Полное наименование и описание. После создания классификатора, вы можете присвоить его объекту.

Позднее классификаторы можно отредактировать, отследить историю изменений каждого классификатора или удалить его из системы.

Создание нового классификатора

Деактивация классификаторов
Системные наборы классификаторов "ПерсональныеДанные", "Персональные идентификаторы" можно деактивировать, если вы не собираетесь их использовать. Деактивированные классификаторы невозможно назначить объектам и использовать их в качестве фильтров для поиска объектов.

Чтобы деактивировать набор раскройте меню внутри набора классификаторов и нажмите Деактивировать

Создание нового классификатора

Дашборд ADC
Дашборд Arenadata Catalog предназначен для анализа состояния наполненности системы.

Вы можете просмотреть:

  1. Общее количество источников данных в системе, разделенных по типу.
  2. Процент источников данных с указанным владельцем.
  3. Процент источников данных с заполненным описанием.
  4. Процент источников данных по уровням бизнес-критичности.
  5. Рейтинг самых просматриваемых источников данных.
  6. Рейтинг самых активных пользователей.

На основе 3ей и 4ой метрик вы можете создавать задачи KPI для администратора CDO: к какой дате какой процент наполненности хотите получить.

Обзор дашборда ADC

Для того чтобы данные появлись в разделе Аналитика, необходимо настроить загрузку данных в этот дашборд. В разделе настроек системы Arenadata Catalog– Аналитика добавьте загрузку данных с типом Data Insight. И настройте для нее необходимое расписание. Соответственно с этим расписанием будет обновляться дашборд Arenadata Catalog.

Как настроить загрузку данных в дашборд ADC

Уведомления
Настройка уведомлений и наполнения ленты активности выполняются в разделе Уведомления в настройках. Администратор настраивает условия и фильтры для уведомлений, пользователи определяются ролевой моделью: администраторы, владельцы, подписчики.

Если вы хотите получать уведомления по email необходимо настроить SMTP-сервер.
Email
Начиная с версии Arenadata Catalog v 0.4.0 настройка почтового сервера добавлена на UI, чтобы вы могли легко
отслеживать эти параметры и изменять их. Вы можете найти этот раздел в Настройках с названием Email.

Настройка почтового сервера

После изменения этих параметров требуется рестарт сервера приложения, для вступления изменений в силу.
Использование пользовательских шаблонов писем
Начиная с версии ADC 0.4.0 доступно использование своих шаблонов писем. Требования и инструкция по использованию шаблонов:

  1. Шаблоны должны быть добавлены в специальную директорию (см. ниже).
  2. Шаблоны должны быть быть в кодировке UTF-8, в формате ftl, имена файлов должны заканчиваться соответствующим расширением.
  3. Шаблоны можно установить для событий:
  • Создание сущности - entityCreated
  • Обновление сущности - entityUpdated
  • Удаление сущности - entityDeleted
  • Произвольное изменение сущности - changeEvent
4. Выбор шаблона происходит по следующему алгоритму:
4.1 Если специальная директория настроена (email_template_base_dir_path (см. ниже) установлена), то:
  • Сперва выбирается наиболее специфичный шаблон соответствующий событию и типу сущности, т.е. с именем соответсвующим паттерну {eventType}_{entityType}.ftl . Например entityCreated_glossaryTerm.ftl. Если такого нет, то:
  • Выбирается шаблон в соответствии с событием, т.е. с именем соответсвующим паттерну {eventType}.ftl. Например entityCreated.ftl. Если такого нет, то
  • Выбирается шаблон с именем changeEvent.ftl. Если такого нет, то
  • Выбирается шаблон по умолчанию, входящий в поставку приложения.
4.2 Если специальная директория не настроена (email_template_base_dir_path (см. ниже) не установлена), то выбирается шаблон по умолчанию, входящий в поставку приложения.

5. Шаблонам доступны следующие текстовые переменные:
  • ‘userName’ - имя получателя
  • ‘updateBy’ - имя последнего редактора сущности
  • ‘entityUrl’ - ссылка на сущность
  • ‘changeMessage’ - сообщение о изменении (пустое для создания)
6  Установка и настройка пути директории с шаблонами:

6.1. Создать настройку с “name”: “email_template_base_dir_path” и “value”: “ABSOLUTE-OR-RELATIVE-YOUR-PATH” и произвольным “description”.
Эндпоинт - http://localhost:8585/swagger.html#operation/createAdcSettings

Пример:

curl --location 'http://localhost:8585/api/v1/adcSettings/' \
--header 'Content-Type: application/json' \
--data '{
    "name": "email_template_base_dir_path",
    "description": "",
    "value": "ABSOLUTE-OR-RELATIVE-YOUR-PATH"
}'
6.2 Найти id настройки для использования при обновлении и удалении.
Эндпоинт - http://localhost:8585/swagger.html#operation/getAdcSettingsByName

Пример:

curl --location 'http://localhost:8585/api/v1/adcSettings/name/email_template_base_dir_path'
6.3. Изменить путь к директории.
Эндпоинт - http://localhost:8585/swagger.html#operation/patchAdcSettings

Пример:

curl --location --request PATCH 'http://localhost:8585/api/v1/adcSettings/9ef4bd05-2395-4ad5-a834-ac4f553355ce' \
--header 'Content-Type: application/json-patch+json' \
--data '[
    {
        "op": "replace",
        "path": "/value",
        "value": "SOME-OTHER-PATH"
    }
]'
6.4. Удалить настройку (возвращение к использованию шаблона по умолчанию входящего в поставку)
Эндпоинт - http://localhost:8585/swagger.html#operation/deleteAdcSettings

Пример:

curl --location 'http://localhost:8585/api/v1/adcSettings/name/email_template_base_dir_path'
Пример шаблона
Настройка почтового сервера для версий ниже v 0.4.0
Используя информацию для вашего SMTP-сервера, вы можете настроить Arenadata Catalog для отправки оповещений по электронной почте, обновив приведенный ниже раздел файла openmetadata.yaml.

email:
  emailingEntity: ${OM_EMAIL_ENTITY:-"OpenMetadata"} -> Company Name (Optional)
  supportUrl: ${OM_SUPPORT_URL:-"https://slack.open-metadata.org"} -> SupportUrl (Optional)
  enableSmtpServer : ${AUTHORIZER_ENABLE_SMTP:-false} -> True/False
  openMetadataUrl: ${OPENMETADATA_SERVER_URL:-""} -> {http/https}://{your_domain}
  senderMail: ${OPENMETADATA_SMTP_SENDER_MAIL}
  serverEndpoint: ${SMTP_SERVER_ENDPOINT:-""} -> (Ex :- smtp.gmail.com)
  serverPort: ${SMTP_SERVER_PORT:-""} -> (SSL/TLS port)
  username: ${SMTP_SERVER_USERNAME:-""} -> (SMTP Server Username)
  password: ${SMTP_SERVER_PWD:-""} -> (SMTP Server Password)
  transportationStrategy: ${SMTP_SERVER_STRATEGY:-"SMTP_TLS"}
Webhook
Чтобы настроить webhook, вы можете просто использовать URL конечной точки, куда вы хотите отправить свое оповещение. Кроме того, вы можете настроить следующий параметр:

  • Размер пакета: размер пакета, который будет отправлен на конечную точку.
  • Тайм-аут соединения: тайм-аут для соединения.
  • Секретный ключ: Секретный ключ может быть использован для защиты соединения webhook.
Slack
Для настройки slack вам нужно будет получить URL конечной точки канала, куда вы хотите отправлять оповещения. Кроме того, вы можете настроить следующий параметр:

  • Размер пакета: размер пакета, который будет отправлен на конечную точку.
  • Тайм-аут соединения: тайм-аут для соединения.
  • Секретный ключ: Секретный ключ может быть использован для защиты соединения webhook.
Microsoft Teams
Для настройки уведомление в Teams вам нужно будет получить URL конечной точки, если это канал, по которому вы хотите отправлять оповещения. Вы можете найти это, перейдя на канал команд, где вы хотите, чтобы сообщения отображались, щелкнув три точки и нажав «Connectors». Затем добавьте соединение «Incoming Webhook». Скопируйте URL-адрес этого соединения и укажите его здесь, чтобы открыть метаданные. Это может быть в форме https://your-domain.webhook.office.com/webhookb2/…@…/IncomingWebhook /…/….

Также вы можете настроить:

  • Размер пакета: размер пакета, который будет отправлен на конечную точку.
  • Тайм-аут соединения: тайм-аут для соединения.
  • Секретный ключ: Секретный ключ может быть использован для защиты соединения webhook.
Настройка уведомлений в системе
Чтобы настроить событие и получателей уведомления, перейдите в раздел Уведомления в Настройках. И нажмите на кнопку Создать оповещение.

Для нового оповещения необходимо заполнить следующие характеристики:

  1. Наименование оповещения
  2. Описание оповещения
  3. Условие оповещения- укажите конкретные типы объектов, на которые распространяется данное уведомление. Также можно указать все типы объектов.
  4. Фильтры- укажите какое событие должно произойти с объектом, чтобы отправилось данное уведомление.
  5. Назначение- укажите метод доставки уведомления: email, webhook, MS Teams, Slack.

Как настроить оповещения в системе

Управление серверными оповещениями
Во время работы пользователи получают уведомления внутри Arenadata Catalog, например, об успешном выполнении какого-либо действия. Эти уведомления зафиксированы и помогают пользователям быть уверенными в своих действиях или опознать ошибку. Но в системе могут встречаться ошибки с однозначным определением индекса объекта.

Ошибка индекса Elasticsearch

Эти ошибки могут возникнуть в момент переиндексации или при проблемах с Elasticsearch. Пользователям они выводятся для того, чтобы при необходимости они могли передать идентификатор ошибки в техническую поддержку. Данный идентификатор позволяет однозначно определить событие, которое вызвало ошибку.

При необходимости вы можете скрыть данные уведомления от пользователей следующим методом:

curl --location --request PUT 'host/api/v1/system/settings' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--data '{
    "config_type": "uiErrorPresentationConfiguration",
    "config_value": {
        "ignoreInternalServerError": true
    }
}'
Управляя значением true/false, вы также сможете вернуть отображение уведомлений.
Кастомизация интерфейса
Arenadata Catalog позволяет вам управлять логотипом приложения и цветами интерфейса. Эти параметры выполняются администратором в разделе Настройки.
Использование логотипа организации
Поменять логотип приложения можно в разделе Пользовательский логотип. Для этого перейдите в раздел, нажмите кнопку Редактировать и следуйте приложенной к разделу инструкции.

Изменение логотипа

Кастомизация цветов
Изменить цвета приложения можно в разделе Кастомизация цветов. Вы можете изменить отдельно цвет шапки портала, а также основные и дополнительные цвета интерфейса. Пропишите нужные коды цветов и после сохранения все изменения будут применены.

Кастомизация интерфейса

В режиме предпросмотра вы можете проверить выполненную настройку.