107 lines
6.8 KiB
Markdown
107 lines
6.8 KiB
Markdown
# Инструменты автоматизации Superset
|
||
|
||
## Обзор
|
||
Этот репозиторий содержит Python-скрипты и библиотеку (`superset_tool`) для автоматизации задач в Apache Superset, таких как:
|
||
- **Резервное копирование**: Экспорт всех дашбордов из экземпляра Superset в локальное хранилище.
|
||
- **Миграция**: Перенос и преобразование дашбордов между разными средами Superset (например, Development, Sandbox, Production).
|
||
|
||
## Структура проекта
|
||
- `backup_script.py`: Основной скрипт для выполнения запланированного резервного копирования дашбордов Superset.
|
||
- `migration_script.py`: Основной скрипт для переноса конкретных дашбордов между окружениями, включая переопределение соединений с базами данных.
|
||
- `search_script.py`: Скрипт для поиска данных во всех доступных датасетах на сервере
|
||
- `run_mapper.py`: CLI-скрипт для маппинга метаданных датасетов.
|
||
- `superset_tool/`:
|
||
- `client.py`: Python-клиент для взаимодействия с API Superset.
|
||
- `exceptions.py`: Пользовательские классы исключений для структурированной обработки ошибок.
|
||
- `models.py`: Pydantic-модели для валидации конфигурационных данных.
|
||
- `utils/`:
|
||
- `fileio.py`: Утилиты для работы с файловой системой (работа с архивами, парсинг YAML).
|
||
- `logger.py`: Конфигурация логгера для единообразного логирования в проекте.
|
||
- `network.py`: HTTP-клиент для сетевых запросов с обработкой аутентификации и повторных попыток.
|
||
- `init_clients.py`: Утилита для инициализации клиентов Superset для разных окружений.
|
||
- `dataset_mapper.py`: Логика маппинга метаданных датасетов.
|
||
|
||
## Настройка
|
||
|
||
### Требования
|
||
- Python 3.9+
|
||
- `pip` для управления пакетами.
|
||
- `keyring` для безопасного хранения паролей.
|
||
|
||
### Установка
|
||
1. **Клонируйте репозиторий:**
|
||
```bash
|
||
git clone https://prod.gitlab.dwh.rusal.com/dwh_bi/superset-tools.git
|
||
cd superset-tools
|
||
```
|
||
2. **Установите зависимости:**
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
(Возможно, потребуется создать `requirements.txt` с `pydantic`, `requests`, `keyring`, `PyYAML`, `urllib3`)
|
||
3. **Настройте пароли:**
|
||
Используйте `keyring` для хранения паролей API-пользователей Superset.
|
||
```python
|
||
import keyring
|
||
keyring.set_password("system", "dev migrate", "пароль пользователя migrate_user")
|
||
keyring.set_password("system", "prod migrate", "пароль пользователя migrate_user")
|
||
keyring.set_password("system", "sandbox migrate", "пароль пользователя migrate_user")
|
||
```
|
||
|
||
## Использование
|
||
|
||
### Скрипт резервного копирования (`backup_script.py`)
|
||
Для создания резервных копий дашбордов из настроенных окружений Superset:
|
||
```bash
|
||
python backup_script.py
|
||
```
|
||
Резервные копии сохраняются в `P:\Superset\010 Бекапы\` по умолчанию. Логи хранятся в `P:\Superset\010 Бекапы\Logs`.
|
||
|
||
### Скрипт миграции (`migration_script.py`)
|
||
Для переноса конкретного дашборда:
|
||
```bash
|
||
python migration_script.py
|
||
```
|
||
|
||
### Скрипт поиска (`search_script.py`)
|
||
Для поиска по текстовым паттернам в метаданных датасетов Superset:
|
||
```bash
|
||
python search_script.py
|
||
```
|
||
Скрипт использует регулярные выражения для поиска в полях датасетов, таких как SQL-запросы. Результаты поиска выводятся в лог и в консоль.
|
||
|
||
### Скрипт маппинга метаданных (`run_mapper.py`)
|
||
Для обновления метаданных датасета (например, verbose names) в Superset:
|
||
```bash
|
||
python run_mapper.py --source <source_type> --dataset-id <dataset_id> [--table-name <table_name>] [--table-schema <table_schema>] [--excel-path <path_to_excel>] [--env <environment>]
|
||
```
|
||
Если вы используете XLSX - файл должен содержать два столбца - column_name | verbose_name
|
||
|
||
|
||
Параметры:
|
||
- `--source`: Источник данных ('postgres', 'excel' или 'both').
|
||
- `--dataset-id`: ID датасета для обновления.
|
||
- `--table-name`: Имя таблицы для PostgreSQL.
|
||
- `--table-schema`: Схема таблицы для PostgreSQL.
|
||
- `--excel-path`: Путь к Excel-файлу.
|
||
- `--env`: Окружение Superset ('dev', 'prod' и т.д.).
|
||
|
||
Пример использования:
|
||
```bash
|
||
python run_mapper.py --source postgres --dataset-id 123 --table-name account_debt --table-schema dm_view --env dev
|
||
|
||
python run_mapper.py --source=excel --dataset-id=286 --excel-path=H:\dev\ss-tools\286_map.xlsx --env=dev
|
||
```
|
||
|
||
## Логирование
|
||
Логи пишутся в файл в директории `Logs` (например, `P:\Superset\010 Бекапы\Logs` для резервных копий) и выводятся в консоль. Уровень логирования по умолчанию — `INFO`.
|
||
|
||
## Разработка и вклад
|
||
- Следуйте **Semantic Code Generation Protocol** (см. `semantic_protocol.md`):
|
||
- Все определения обернуты в `[DEF]...[/DEF]`.
|
||
- Контракты (`@PRE`, `@POST`) определяются ДО реализации.
|
||
- Строгая типизация и иммутабельность архитектурных решений.
|
||
- Соблюдайте Конституцию проекта (`.specify/memory/constitution.md`).
|
||
- Используйте `Pydantic`-модели для валидации данных.
|
||
- Реализуйте всестороннюю обработку ошибок с помощью пользовательских исключений.
|