MapGL JS API

Сервис MapGL JS API реализует JavaScript API для показа векторной карты 2GIS в веб-приложениях и сайтах.

Сервис представляет собой сервер nginx, который позволяет скачать главную библиотеку для работы с картой (файл api.js) и основной (дневной) стиль карты (директория style).

Карта при своей работе использует следующие бекенды:

Тайловый сервер
Сервер пробок
Сервер ключей

Адреса этих бекендов настраиваются при помощи переменных окружения, которые указываются при развертывании сервиса. По умолчанию бекенды указывают на сервера компании 2GIS.

Для отобржения RTL-языков карта дополнительно загружает плагин, его адрес также указывается при развертывании сервиса. переменными окружения.

Требования

Характеристика	Рекомендованное значение
Количество CPU, на один под	2
Объем памяти (RAM), на один под	2 Гб
Минимальное количество подов (для обеспечения базовой отказоустойчивости)	2

Установка

Для установки сервиса рекомендуется использовать Helm-чарт.

Важно! Сервис MapGL JS API должен быть доступен для клиентских запросов, так как JavaScript-библиотека и стиль карты скачиваются напрямую браузером.

Перед установкой сервиса нужно указать репозиторий, в котором хранится скачанный образ сервиса. Для это можно создать настроечный YAML-файл со следующим содержанием:

settings.yaml

image:
    repository: your-docker-hub/2gis/mapgl-js-api
    tag: 1.0.0

В этом файле можно указать и другие настройки: пути до бекендов, ресурсные ограничения, использование Ingress и т.д.

image:
    repository: your-docker-hub/2gis/mapgl-js-api
    tag: 1.0.0

env:
    PUBLIC_HOST: mapgl.public.your-host
    MAPGL_TILESERVER: tileserver.your-host
    MAPGL_TRAFFICSERVER: trafficserver.your-host
    MAPGL_KEYSERVER: keyserver.your-host

resources:
    requests:
        cpu: 30m
        memory: 32M
    limits:
        cpu: 100m
        memory: 64M

Значения из этого файла будут подставлены в конфигурационные файлы из директории templates.

После создания файла YAML-файла, нужно вызвать команду helm install и указать имя созданного файла:

helm install mapgl . -f settings.yaml

Чтобы обновить сервис после изменения настроек или образа сервиса, нужно вызвать команду helm upgrade:

helm upgrade mapgl . -f settings.yaml

Настройка сервиса

Сервис карты настраивается при помощи переменных окружения. Эти переменные указываются в разделе env настроечного файла settings.yaml.

PUBLIC_HOST Хост на котором публикуется сервис карты.
MAPGL_TILESERVER (значение по умолчанию tile{subdomain}-sdk.maps.2gis.com) Хост тайлового сервера
MAPGL_TRAFFICSERVER (значение по умолчанию traffic0.edromaps.2gis.com) Хост сервера пробок
MAPGL_KEYSERVER (значение по умолчанию keys.api.2gis.com) Хост сервера ключей.
MAPGL_RTLPLUGIN (значение по умолчанию https://mapgl.2gis.com/api/js/plugins/rtl-v1.0.0.js) URL плагина поддержки RTL-языков (арабский, иврит и т.п.).
MAPGL_RTLPLUGINHASH (значение по умолчанию sha512-YAPPEl+Atvsm/cMkrfWefmlQLAlKTGaqFjIkI6urAnDgam2uTVEVVnZZEhHCa91JjYYxa5yr4Ndb4Vl3NUovfA==) хеш плагина поддержки арабского. Используется для предотвращения подмены содержимого плагина при его загрузке.

Тайловый сервер

Кроме JavaScript-библиотеки и файлов стиля, для отображения карты нужны тайлы. Тайлы - это квадратные изображения, из которых формируется основное изображение карты (см. пример). Использование тайлов позволяет не загружать карту целиком, а подгружать нужные фрагменты при изменении координат или масштаба карты.

Для отображения тайлов используется отдельный сервис - Tileserver API. В данный момент этот сервис находится в разработке, поэтому для обработки запросов временно используется основной сервер 2GIS (tile[0-3].maps.2gis.com).

Проверка работы

Чтобы проверить работу сервиса, можно создать и открыть в браузере следующий HTML-файл. Строку mapgl.service.published.host нужно заменить на адрес опубликованного сервиса MapGL JS API.

<html>
    <head>
        <title>MapGL JS API. On-Premise</title>
        <style>
            #map {
                width: 100%;
                height: 100%;
            }
        </style>
    </head>

    <body>
        <div id="map"></div>
        <script src="http://mapgl.service.published.host/api.js"></script>
        <script>
            const map = new mapgl.Map('map', {
                key: 'your key',
                center: [55.31878, 25.23584],
                style: 'http://mapgl.service.published.host/style/',
                styleOptions: {
                    iconsPath: 'http://mapgl.service.published.host/style/images/',
                    fontsPath: 'http://mapgl.service.published.host/style/fonts/',
                },
                zoom: 13,
            });
        </script>
    </body>
</html>