Параметры запросов

Mapbox GL JS строит визуализацию карты на основе множества сетевых запросов, которые выполняются динамически в процессе работы приложения. Основные типы загружаемых ресурсов:

  • стили (style.json)
  • векторные тайлы (vector tiles)
  • растровые тайлы (raster tiles)
  • источники данных GeoJSON
  • шрифты (glyphs)
  • спрайты (sprites)
  • изображения и ресурсы слоёв

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

Параметры запроса в transformRequest

Ключевой механизм управления сетевыми запросами — функция transformRequest. Она перехватывает каждый URL перед отправкой и позволяет модифицировать его или заголовки.

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v12',
  transformRequest: (url, resourceType) => {
    return {
      url: url,
      headers: {
        'X-Custom-Header': 'value'
      }
    };
  }
});

Основные параметры объекта возврата:

  • url — конечный адрес запроса
  • headers — HTTP-заголовки
  • credentials — политика передачи cookies (same-origin, include, omit)
  • method — HTTP-метод (в ограниченных сценариях)

Механизм применяется ко всем типам ресурсов, включая тайлы и стили.

Query-параметры источников данных

При подключении источников (sources) Mapbox GL JS формирует URL, в который могут быть встроены query-параметры. Наиболее типичный пример — векторные тайлы:

map.addSource('cities', {
  type: 'vector',
  tiles: [
    'https://example.com/tiles/{z}/{x}/{y}.pbf?dataset=urban&year=2024'
  ],
  minzoom: 0,
  maxzoom: 14
});

Здесь query-параметры:

  • dataset=urban — выбор слоя данных на сервере
  • year=2024 — фильтрация данных на стороне источника

Mapbox GL JS не интерпретирует параметры, а передаёт их напрямую серверу тайлов.

Параметры векторных тайлов {z}/{x}/{y}

Векторные тайлы используют шаблон:

/{z}/{x}/{y}.pbf

Допустимые расширения query:

?access_token=...
?version=...
?layer=...
?filter=...

Пример:

tiles: [
  'https://api.example.com/vector/{z}/{x}/{y}.pbf?layer=roads&quality=high'
]

Сервер может интерпретировать параметры следующим образом:

  • layer — выбор конкретного слоя внутри тайла
  • quality — уровень детализации
  • format — альтернативный формат кодирования

Параметры доступа и авторизации

Mapbox GL JS автоматически добавляет токен доступа в большинство запросов к Mapbox API.

Пример:

https://api.mapbox.com/v4/mapbox.streets/0/0/0.vector.pbf?access_token=TOKEN

Основные параметры:

  • access_token — ключ доступа
  • sku — идентификатор биллинга (внутренний параметр)
  • client — идентификатор клиента SDK

Эти параметры критичны для работы с Mapbox инфраструктурой и не должны удаляться при трансформации запросов.

Параметры стилей (style.json)

Стиль карты также загружается через HTTP-запрос и может содержать вложенные параметры источников.

mapboxgl.Map({
  style: 'mapbox://styles/mapbox/light-v11'
});

Фактический запрос:

https://api.mapbox.com/styles/v1/mapbox/light-v11?access_token=TOKEN

Дополнительные параметры:

  • fresh=true — игнорирование кэша
  • optimize=true — оптимизация ответа сервера
  • debug=true — включение диагностических данных

Параметры шрифтов (glyphs)

Шрифты загружаются как диапазоны символов:

https://api.mapbox.com/fonts/v1/{username}/{fontstack}/{range}.pbf

Пример:

https://api.mapbox.com/fonts/v1/mapbox/Arial Unicode MS,Regular/0-255.pbf

Параметры:

  • fontstack — список шрифтов через запятую
  • range — диапазон Unicode символов
  • hinting — параметры рендеринга (в некоторых CDN)

Параметры спрайтов (sprites)

Спрайты используются для иконок и UI элементов карты:

https://api.mapbox.com/styles/v1/{style_id}/sprite

Дополнительные форматы:

  • .json — метаданные
  • .png — изображение

Пример:

sprite.png?scale=2&attribution=true

Параметры:

  • scale — масштабирование (1x, 2x)
  • attribution — включение атрибуции ресурсов
  • theme — выбор темы иконок (в кастомных реализациях)

Параметры GeoJSON источников

GeoJSON может загружаться как удалённый ресурс:

map.addSource('points', {
  type: 'geojson',
  data: 'https://example.com/data/points.json?version=12'
});

или как inline-объект:

data: {
  type: 'FeatureCollection',
  features: []
}

Поддерживаемые параметры URL:

  • version — управление кэшированием
  • bbox — серверная фильтрация по границам
  • limit — ограничение количества объектов

Параметры фильтрации на уровне слоёв

Хотя это не HTTP query-параметры, фильтры Mapbox GL JS часто рассматриваются как логические параметры запроса данных.

map.addLayer({
  id: 'cities-layer',
  type: 'circle',
  source: 'cities',
  'source-layer': 'urban',
  filter: ['>', ['get', 'population'], 100000]
});

Типы операторов:

  • сравнения: >, <, ==, !=
  • логика: all, any, none
  • принадлежность: in, !in
  • работа с данными: get, has

Фильтр формирует запрос к уже загруженному тайлу, уменьшая объём отображаемых данных.

Параметры выражений (Expressions) как расширенные запросы

Expressions в Mapbox GL JS можно рассматривать как декларативные параметры выборки.

Пример:

'circle-color': [
  'interpolate',
  ['linear'],
  ['get', 'value'],
  0, '#2DC4B2',
  100, '#3BB3C3',
  200, '#669EC4'
]

Здесь параметры:

  • источник значения: get
  • метод интерполяции: linear
  • диапазоны значений

Expressions выполняются на GPU и CPU в зависимости от типа слоя.

Параметры загрузки тайлов (TileRequest)

Каждый тайл может быть запрошен с набором внутренних параметров:

  • tileSize — размер тайла (512 или 256)
  • minzoom / maxzoom — диапазон загрузки
  • reparseOverscaled — переразбор масштабированных тайлов
  • bounds — ограничение географической области

Пример:

map.addSource('buildings', {
  type: 'vector',
  url: 'mapbox://mapbox.3d-buildings',
  minzoom: 14,
  maxzoom: 16
});

Кэширование и параметры повторных запросов

Mapbox GL JS активно использует кэширование на уровне:

  • браузера
  • памяти WebGL
  • внутреннего tile cache

Параметры влияния:

  • cacheControl — управление HTTP-кэшем
  • maxTileCacheSize — размер локального кэша
  • refreshExpiredTiles — перезагрузка устаревших тайлов

Изменение URL query-параметров автоматически инвалидирует кэш:

tiles.pbf?version=1
tiles.pbf?version=2

Параметры кастомных источников данных

При использовании кастомных источников через Source API возможны дополнительные параметры:

class CustomSource {
  loadTile(z, x, y, options) {
    const url = `/tiles/${z}/${x}/${y}?debug=${options.debug}`;
  }
}

Передаваемые параметры:

  • z, x, y — координаты тайла
  • tileSize
  • transform
  • overzoom

Параметры производительности запросов

Сетевое поведение Mapbox GL JS может настраиваться через:

  • maxParallelImageRequests
  • maxParallelTileRequests
  • workerCount

Эти параметры косвенно влияют на формирование очереди запросов и их конкурентность.

const map = new mapboxgl.Map({
  maxParallelTileRequests: 16,
  maxParallelImageRequests: 8
});

Параметры региональных ограничений (bounds-based requests)

Ограничение области загрузки влияет на формирование запросов тайлов:

map.setMaxBounds([
  [71.0, 48.0],
  [87.0, 55.0]
]);

Эти параметры не передаются в URL напрямую, но влияют на вычисление набора {z}/{x}/{y} тайлов, которые будут запрошены.

Параметры изображений источников (ImageSource)

map.addSource('overlay', {
  type: 'image',
  url: 'https://example.com/image.png',
  coordinates: [...]
});

Поддерживаемые параметры:

  • url — источник изображения
  • coordinates — геопривязка (4 угла)
  • opacity — через слой, не запрос
  • tolerance — точность отрисовки

Параметры retry и устойчивости сети

Mapbox GL JS реализует повторные попытки запросов при ошибках сети:

  • maxRetries — количество повторов
  • retryDelay — задержка между попытками
  • timeout — тайм-аут запроса

Эти параметры влияют на поведение загрузки тайлов и стилей, особенно при нестабильном соединении.

Оглавление