Перейти к содержимому
ДефиникаДефиника · Документация

YAML-проект: импорт, экспорт, развёртывание из CI

Доступно: аналитикам и администраторам

Модель можно хранить в git как набор YAML-файлов: править в редакторе, проверять в pull request и разворачивать из CI. Эта страница — для тех, кто так работает.

YAML одного объекта

Заголовок раздела «YAML одного объекта»

У любого объекта в модели есть переключатель «показать как YAML» / «показать как форму». Показывается последняя сохранённая версия объекта.

Структура проекта

Заголовок раздела «Структура проекта»
model/
├── project.yaml
├── tables/
├── metrics/
└── dimensions/

Папка, в которой лежит project.yaml, а рядом с ним tables/, metrics/ и dimensions/.

Экспорт

Заголовок раздела «Экспорт»

В режиме редактирования нажмите «Экспорт». Скачается развёрнутая модель как YAML-проект (.zip), который можно загрузить обратно через импорт. Черновик в экспорт не попадает.

Импорт

Заголовок раздела «Импорт»

  1. В режиме редактирования нажмите «Импорт». Откроется «Импорт YAML-проекта».

  2. Перетащите папку модели или её .zip, либо нажмите «Выбрать папку» / «Выбрать .zip».

  3. Посмотрите, что изменится: сколько объектов «новых», «изменённых» и «помечено на удаление». Удаление — такая же строка черновика, как и любая другая: если объект нужно оставить, отмените его удаление в черновике.

  4. Нажмите «Перенести в черновик».

  5. Сохраните черновик как обычно: проверки на хранилище выполнятся при сохранении.

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

Вернуть прежнюю версию

Заголовок раздела «Вернуть прежнюю версию»

Истории версий в интерфейсе нет. Если модель хранится в git, импортируйте нужный прошлый коммит проекта и сохраните — получится новая версия с прежним содержимым.

Развёртывание из CI

Заголовок раздела «Развёртывание из CI»

Конвейер может развернуть модель одним запросом: POST /api/orgs/<организация>/model/deploy. Он проходит те же этапы, что «Сохранить» в интерфейсе: форма, компиляция, проверки на хранилище.

Сервисный аккаунт и токен

Заголовок раздела «Сервисный аккаунт и токен»

Конвейер работает от имени сервисного аккаунта, а не человека: личный токен перестанет работать, когда сотрудник уйдёт. Администратор организации создаёт аккаунт и токен:

  1. «Организация → Сервисные аккаунты» → «Создать сервисный аккаунт», роль «Аналитик» или «Администратор».
  2. «Создать токен» с областью доступа «Развёртывание модели» и нужным «Срок действия».
  3. Скопируйте токен — больше он показан не будет — и сохраните его в секретах CI, а не в репозитории.

Подробнее: Сервисные аккаунты и токены.

Запрос

Заголовок раздела «Запрос»

Заархивируйте папку модели и отправьте .zip в поле files. Необязательное поле note станет заметкой к версии.

Окно терминала
HUB=https://definica.example.ru   # адрес Дефиники вашей компании
ORG=acme                          # короткое имя организации из адреса


(cd model && zip -qr ../model.zip .)
curl -sS -o deploy.json -w '%{http_code}' \
  -X POST "$HUB/api/orgs/$ORG/model/deploy" \
  -H "Authorization: Bearer $DEFINICA_DEPLOY_TOKEN" \
  -F "files=@model.zip;type=application/zip" \
  -F "note=$GITHUB_REPOSITORY@$GITHUB_SHA"

Если проект ничего не меняет, новая версия не создаётся. Если изменения есть, они проходят проверки и разворачиваются одной версией, автор которой — сервисный аккаунт. Черновики людей развёртывание не трогает.