Карты | On-Premise | 2GIS Documentation
On-Premise

MapGL JS API

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

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

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

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

Адреса этих бекендов настраиваются при помощи переменных окружения, которые указываются при развертывании сервиса. По умолчанию бекенды указывают на сервера компании 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>