Добавление новой карты в Apache Superset
В этой статье мы поговорим о том, как добавить карту страны в репозиторий Superset.
К сожалению, интересующая меня карта Южная Африки отсутствует в списке доступных стран для текущей версии Superset 2.1.0. Однако я могу ее добавить.
Чтобы сделать это, необходимо следовать инструкциям, приведенным в официальной документации. Только тогда мы сможем получить карту Южной Африки в необходимом нам формате GeoJSON.
Давайте посмотрим, как можно добавить в Superset карту страны, которой нет в основном списке Superset.
Обязательные условия:
- Git;
- Менеджер пакетов для Javascript (yarn или npm)
Шаг 1 — Получение карты
Первый шаг - это поиск или создание карты интересующей Вас страны в формате GeoJSON. Мне пришлось проверить несколько онлайн-источников, чтобы, в конце концов, найти то, что мне нужно.
Если карта нужной Вам страны представлена в других форматах, таких как shapefile или TopoJSON, Вы можно преобразовать ее в формат GeoJSON с помощью офлайн - или онлайн-инструментов, например, воспользовавшись этим сайтом.
Вы также можете попробовать сгенерировать файл карты с помощью инструмента, представленным в репозитории Superset (ссылка). Я же решил поискать и скачать нужную мне карту из внешнего источника.
Одним из важных аспектов является выполнение требования Superset о включении кодов ISO 3166-2 для провинций или регионов в карту страны. Для того чтобы включить соответствующие коды для каждой провинции в файл, мне пришлось вручную обновлять файл карты и добавить к ним пару ISO-значение-ключ:
{ "type": "Feature",
"properties": { "id": "8", "ISO": "ZA-WC*", "NAME_1": "Western Cape",
"CODE": "WC", "PROVINCE": "Western Cape"...}
}
Шаг 2 — Форк Apache Superset
Чтобы не повторять эту операцию каждый раз, когда я хочу обновиться при появлении новой версии Superset, я сделал форк репозитория Superset в репозиторий моей организации. Таким образом, при появлении новой версии мне нужно будет лишь объединить свою версию с изменениями в репозитории.
Шаг 3 — Клонирование форк-репозитория
После форка официального репозитория клонируйте репозиторий с «форкнутой» страницы на рабочую страницу. Я предпочитаю загружать из последнего форка (на момент написания данной статьи это v2.1.0), а не из мастер-ветки. Затем для того, чтобы не загружать всю истории коммитов, которая мне не нужна, я указываю параметр --depth 1. Обязательно проверьте клонированный репозиторий на новой локальной ветке с аналогичным названием (например, v2.1.0):
# <organisation> should be replated in the link $ git clone --depth 1 --branch 2.1.0 https://github.com/<oranisation>/superset.git $ git checkout -b v2.1.0
Шаг 4 — Настройка nvm
Если Вы внимательно посмотрите на файлы и каталоги в загруженном репозитории, то обязательно увидите каталог под названием superset-frontend. Именно он-то нам и нужен.
Для того, чтобы иметь возможность объединить несколько файлов после добавления интересующей нас карты, нам понадобится менеджер пакетов для Javascript, такой как NodeJS NPM или Yarn.
Если у Вас установлен nvm, то для того, чтобы установить нужную нам версию node из источника, указанного в файле .nvmrc (например, v16.9.1), в каталог superset-frontend, достаточно выполнить следующую команду:
# install nvm from version specified in .nvmrc file in the following directory $ cd superset-frontend $ nvm install $ nvm use
Если у Вас уже установлена нужная версия узла, Вы можете просто выполнить команду nvm use для перехода на нужную Вам версию.
После успешного выполнения вышеуказанных команд явно укажите нужную версию узла, содержащуюся в файле .nvmrc:
$ nvm current v16.9.1
Шаг 5 — Построение и установка зависимостей
После успешного выполнения вышеуказанных настроек необходимо выполнить сборку с помощью команды npm ci. В приведенном ниже фрагменте кода я установил переменную окружения PUPPETEER_SKIP_DOWNLOAD, на которые ссылаются пользователи:
# clean and install dependencies $ npm config set fetch-retry-maxtimeout 240000 $ export PUPPETEER_SKIP_DOWNLOAD='true' $ npm ci
Если сборка прошла успешно, можно запустить и просмотреть плагины диаграмм в браузере, собрав и запустив пакет плагинов storybook следующим образом:
$ npm run plugins:storybook
Шаг 6 — Добавление карты
Для того чтобы добавить новую карту, необходимо внести следующие два изменения:
- Добавьте новый файл geo-json карты в каталог стран в ./plugins/legacy-plugin-chart-country-map/src/countries/
- Откройте и отредактируйте файл countries.ts, сохраненный в подкаталоге plugins/legacy-plugin-chart-country-map/src/, и добавьте название страны в несколько мест.
В первой части файла добавьте оператор import с указанием пути и имени geo-json-файла Вашей карты, сохраненного в предыдущем шаге. В моем случае я добавил строку для импорта карты south_africa во второй строке:
import slovenia from './countries/slovenia.geojson'; import south_africa from './countries/south_africa.geojson'; import sweden from './countries/sweden.geojson';
Также необходимо добавить название страны в список стран:
export const countries = {
...
slovenia,
south_africa,
spain,
...
}
Шаг 7 — Построение ассетов
После внесения необходимых изменений в код мы можем собрать фронтенд-ассеты с помощью npm:
$ npm run build
Если сборка завершена успешно и без каких-либо ошибок, скомпилированные ассеты будут сгенерированы в superset/static/assets.
Шаг 8 — Создание приложения Superset
В качестве завершающего шага нам нужно создать приложение на python, которое будет включать все внесенные изменения.
Перейдите в родительский каталог и выполните следующую команду, которая установит необходимые пакеты python из прилагаемого файла setup.py:
$ pip install .
Убедитесь в том, что предварительно Вы настроили виртуальную среду python. В случае необходимости обратитесь к официальному руководству.
По окончании процесса создания приложения в каталоге bin виртуальной среды появится исполняемый файл Superset. После этого установите пакет зависимостей.
Развертование в производственной среде
Для работы с локальным приложением Superset описанных выше шагов будет вполне достаточно. Однако для развертывания приложения в производственной среде необходимо зафиксировать изменения и перенести их на Github. Из производственной среды можно клонировать репозиторий и повторить процесс сборки узла и приложения (начиная с шага № 4).
Устранение проблем
Если на каком-либо этапе у Вас не получилось установить зависимости или Вам нужно начать все сначала, в первую очередь удалите сгенерированный каталог node_modules:
$ npm remove node_modules
