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

В этой статье описывается, как установить и настроить сервисы навигации в вашем окружении. Чтобы узнать, как использовать RESTful API, предоставляемые сервисами навигации, обратитесь к документации соответствующих API (можно найти в основном меню сверху на вкладке «Навигация»).

Архитектура

Основные сервисы навигации включают в себя:

Navi-Castle — импортирует данные из S3-хранилища и предоставляет их сервису Navi-Back в требуемом формате.
Navi-Front — получает входящие запросы от приложений и направляет их к Navi-Router и Navi-Back.
Navi-Router — проверяет с помощью сервиса ключей, можно ли выполнить запрос. Затем с помощью системы регионов и правил выполняет маршрутизацию: определяет подходящий сервис Navi-Back, который будет обрабатывать этот запрос.
Navi-Back — обрабатывает запрос.

Distance Matrix Async API — получает запросы пользователя для асинхронной части Distance Matrix API и направляет их к Navi-Back. Взаимодействие Distance Matrix Async API с другими сервисами описано в разделе Обработка асинхронных запросов к Distance Matrix API.

Дополнительные сервисы навигации:

Restrictions API — предоставляет информацию о перекрытиях дорог.
Прокси для API пробок — предоставляет данные о пробках в реальном времени с серверов 2ГИС. Navi-Back использует эту информацию для построения маршрутов с учётом трафика.
TSP API — позволяет решать задачу коммивояжёра (построить кратчайший маршрут обхода точек).

Сервисы навигации используют масштабируемую архитектуру, что позволяет с легкостью распределять обработку входящих запросов между несколькими инстансами Navi-Back:

Navi-Front автоматически обнаруживает установленные инстансы Navi-Router и Navi-Back, проверяя наличие особых меток (labels) для сервисов, установленных в том же пространстве имен (namespace) Kubernetes, что и сам Navi-Front.
Может существовать несколько инстансов Navi-Back, каждый из которых обрабатывает свою часть запросов. Соответственно, каждый инстанс запрашивает у Navi-Castle не все доступные данные, а только их часть, необходимую для работы конкретного инстанса.

Каждый инстанс Navi-Back имеет назначенное для него «правило»: группу из одного или нескольких регионов карты, в рамках которой будет происходить обработка запросов. Правила настраиваются с помощью файла правил. Таким образом, появляется возможность распределять нагрузку и планировать вычислительные ресурсы инстансов Navi-Back в соответствии с этим файлом. Например, один инстанс Navi-Back с малой производительностью может обрабатывать умеренное количество запросов для некоторого небольшого региона, а другой, более производительный инстанс, может обрабатывать большое количество запросов для большего по размерам региона.

Когда Navi-Front получает входящий запрос:

Он передает этот запрос сервису Navi-Router.
Navi-Router использует тот же файл правил, что и Navi-Back, и получает все данные от Navi-Castle. Пользуясь этим файлом и имеющимися данными, Navi-Router выполняет маршрутизацию: находит правило, под которое попадает запрос. Другими словами, Navi-Router определяет, существует ли инстанс Navi-Back, который может обработать этот запрос.

Если запрос успешно проходит проверку в сервисе ключей и существует подходящее для его обработки правило, то Navi-Router отправляет название этого правила Navi-Front.
Navi-Front находит подходящий инстанс Navi-Back, который настроен на работу с правилом, название которого вернул Navi-Router, и передает запрос этому инстансу.
Инстанс Navi-Back обрабатывает запрос и возвращает ответ Navi-Front.
Navi-Front отсылает ответ инициатору запроса.

Сервисы навигации могут быть установлены в разных конфигурациях:

Все сервисы. Это рекомендуемый метод установки, обеспечивающий безопасность, масштабируемость и надежность.
Все сервисы, кроме Distance Matrix Async API. Эта конфигурация рекомендуется, если вам не требуется поддержка расчёта большого количества точек в Distance Matrix API.
Только сервисы Navi-Castle и Navi-Back. В этом случае все входящие запросы обрабатываются непосредственно Navi-Back. Этапы проверки и маршрутизации запроса пропускаются. Рекомендуется использовать такую конфигурацию только в целях тестирования.

Примечание:

Без Navi-Router Navi-Back способен обрабатывать только те запросы, которые попадают под единственное правило, на работу с которым настроен Navi-Back. При распределенных установках для работы сервисов навигации необходимы сервисы Navi-Front и Navi-Router.
В зависимости от ваших требований, вы также можете пропустить установку сервиса Restrictions API, TSP API и прокси для API пробок.

Обработка асинхронных запросов к Distance Matrix API

Для расчёта большого количества точек с помощью Distance Matrix API нужно установить его асинхронную версию: Distance Matrix Async API. Этот сервис является фронтендом к сервису Navi-Back, взаимодействие с которым ведётся с помощью S3-совместимого хранилища и событий в Apache Kafka. Чтобы определить, какой именно инстанс Navi-Back сможет обработать тот или иной запрос, сервис использует данные, загруженные с сервиса Navi-Castle.

Запросы пользователей выполняются асинхронно. После отправки запроса к сервису пользователь должен периодически отправлять дополнительные запросы для получения информации о статусе его выполнения. Информация о состоянии запросов хранится в PostgreSQL.

Архитектура сервисов по обработке асинхронных запросов

Порядок обработки запроса:

Пользователь отправляет запрос.
Сервис Distance Matrix Async API разделяет запрос на подзапросы. Разделение происходит, если размер матрицы расстояний на входе больше границы, установленной в параметре dm.taskSplitSize в конфигурационном файле Distance Matrix Async API.
Сервис Distance Matrix Async API сохраняет данные в хранилище S3.
Сервис Distance Matrix Async API создаёт событие в Apache Kafka. Чтобы определить, в какой именно топик Apache Kafka нужно направить событие, сервис использует данные, заранее загруженные с сервиса Navi-Castle, а также правила, указанные в настройке topicRules.

Если пользователь запросит статус выполнения запроса в этот момент, он получит информацию о том, что запрос ещё выполняется.
Один из инстансов Navi-Attractor читает событие из Apache Kafka, загружает данные запроса из хранилища S3 и производит «притяжку» точек запроса к графу. После успешного или неуспешного завершения работы Navi-Attractor создаёт новое событие в топике, записав результаты вычислений в хранилище S3.
Сервис Distance Matrix Async API читает событие о «притяжке», получает результаты вычислений из S3, создаёт задание для Navi-Back, отправляет оповещение о задании в Apache Kafka.
Один из инстансов Navi-Back читает событие из Apache Kafka, загружает данные запроса из хранилища S3 и производит необходимые вычисления. После успешного или неуспешного завершения работы он создаёт новое событие в топике, указанном в настройке consumerCancelTopic, при необходимости записав результаты вычислений в хранилище S3.
Сервис Distance Matrix Async Merger соединяет ответы всех подзапросов в один ответ и сохраняет результат в хранилище S3.
Сервис Distance Matrix Async API читает событие из Apache Kafka и при необходимости загружает данные ответа из хранилища S3.

Если пользователь запросит статус выполнения запроса в этот момент, он получит информацию о том, что запрос выполнен, а также результат его выполнения.

В некоторых случаях сервис может прервать выполнение запроса, уже отправленного в Navi-Back. Для этого он создаёт события в топиках, указанных в настройках consumerTaskTopic и consumerCancelTopic.

Для коммуникации с другими сервисами Distance Matrix Async API использует топики Apache Kafka следующим образом:

Обмен данными с сервисом Navi-Back:
- Distance Matrix Async API отправляет задачи в Navi-Back через taskTopic. Имя топика указывается в следующих параметрах:
  - kafka.taskTopicRules.topic в конфигурационном файле Distance Matrix Async API;
  - kafka.distanceMatrix.taskTopic в конфигурационном файле Navi-Back.
- Navi-Back отправляет статусы задач в Distance Matrix Async API через statusTopic. Имя топика указывается в следующих параметрах:
  - kafka.oneToManyTopic в конфигурационном файле Distance Matrix Async API;
  - kafka.distanceMatrix.statusTopic в конфигурационном файле Navi-Back.
Обмен данными с сервисом Navi-Attractor:
- Distance Matrix Async API отправляет задачи в Navi-Attractor через taskTopic. Имя топика указывается в следующих параметрах:
  - kafka.attractTopicRules.topic в конфигурационном файле Distance Matrix Async API;
  - kafka.distanceMatrix.taskTopic в конфигурационном файле Navi-Attractor.
- Navi-Attractor отправляет статусы задач в Distance Matrix Async API через statusTopic. Имя топика указывается в следующих параметрах:
  - kafka.attractTopic в конфигурационном файле Distance Matrix Async API;
  - kafka.distanceMatrix.statusTopic в конфигурационном файле Navi-Attractor.
Отмена задач Navi-Back и Navi-Attractor:

Distance Matrix Async API может отменять задачи Navi-Back и Navi-Attractor через cancelTopic (общий топик для обоих сервисов). Имя топика указывается в следующих параметрах:
- kafka.cancelTopic в конфигурационном файле Distance Matrix Async API;
- kafka.distanceMatrix.cancelTopic в конфигурационном файле Navi-Back;
- kafka.distanceMatrix.cancelTopic в конфигурационном файле Navi-Attractor.
Обмен данными с сервисом Distance Matrix Async Merger:
- Distance Matrix Async API отправляет задачи в Distance Matrix Async Merger через mergerTaskTopic. Имя топика указывается в параметре kafka.mergerTaskTopic в конфигурационном файле Distance Matrix Async API.
- Distance Matrix Async Merger отправляет статусы задач в Distance Matrix Async API через mergerStatusTopic. Имя топика указывается в параметре kafka.mergerStatusTopic в конфигурационном файле Distance Matrix Async API.

Решение задачи коммивояжёра

Для решения задачи коммивояжёра (TSP/VRP) установите сервис TSP API. Этот сервис позволяет построить кратчайший по времени или расстоянию маршрут обхода точек одним или несколькими курьерами. TSP API взаимодействует с сервисом Distance Matrix Async API, чтобы получить матрицу расстояний для всех возможных пар точек, а затем выбирает наиболее оптимальную комбинацию этих расстояний для решения задачи.

Архитектура сервисов по решению задачи коммивояжёра

Порядок обработки запроса:

Пользователь отправляет запрос.
Сервис VRP Task Manager сохраняет данные запроса в S3-совместимое хранилище и записывает статус задачи в базу данных PostgreSQL. На этом и следующих этапах пользователь может запрашивать статус решения задачи отдельным запросом.
Сервис VPR Task Manager отправляет сервису Distance Matrix Async API задачу на расчёт матрицы расстояний для всех полученных точек из запроса и обновляет статус задачи.
Distance Matrix Async API записывает результат расчёта в S3-совместимое хранилище. Сервис VPR Task Manager обновляет статус задачи.
На основе рассчитанной матрицы расстояний сервис VRP Solver вычисляет оптимальный маршрут. Сервис VPR Task Manager обновляет статус задачи.
Сервис VRP Solver записывает результат в S3-совместимое хранилище. Сервис VPR Task Manager обновляет статус задачи.
Пользователь запрашивает статус решения задачи, и сервис VPR Task Manager возвращает решение.

Подробнее об использовании TSP API см. в документации.

Работа с Restrictions API

С помощью сервиса Restrictions API вы можете работать с информацией о перекрытиях дорог: получать список активных перекрытий, добавлять новые перекрытия и удалять более не актуальные. Все перекрытия, добавленные через Restrictions API, учитываются при построении маршрутов.

Сервис Restrictions API предоставляет RESTful API для использования в клиентском приложении.

Сервис Restrictions API взаимодействует с сервисами (Navi-Castle и Navi-Back) для получения географических данных. В том числе сервис использует cron-задачу для периодического (раз в час) получения текущей информации о перекрытиях дорог от сервиса Navi-Castle.

Добавление перекрытия дороги

Чтобы добавить перекрытие дороги, отправьте POST-запрос на endpoint /points.

Тело запроса должно содержать JSON-объект со следующими атрибутами:

lat — географическая широта перекрытия.
lon — географическая долгота перекрытия.
start_time — дата и время начала перекрытия в формате RFC 3339 (например, 2020-05-15T15:52:01Z).
end_time — дата и время окончания перекрытия в формате RFC 3339 (например, 2020-05-15T15:52:01Z).

{
    "lat": 54.943207,
    "lon": 82.93057,
    "start_time": "2022-03-01T12:00:00Z",
    "end_time": "2022-04-01T12:00:00Z"
}

Если перекрытие дороги было успешно добавлено, ответ будет содержать UUID, с помощью которого можно обновить или удалить информацию о перекрытии.

Получение активных перекрытий дорог

Чтобы получить список активных перекрытий дорог, отправьте GET-запрос на endpoint /restrictions.

Запрос вернёт следующую информацию:

restriction_id — UUID перекрытия.
edge_geometry — геометрия перекрытия в формате WKT.
start_time — дата и время начала перекрытия в формате RFC 3339 (например, 2020-05-15T15:52:01Z).
end_time — дата и время окончания перекрытия в формате RFC 3339 (например, 2020-05-15T15:52:01Z).

[
    {
        "restriction_id": "ca89008e-186b-4a97-942b-739b646b6952",
        "edge_geometry": "...",
        "start_time": "2022-03-01T12:00:00Z",
        "end_time": "2022-04-01T12:00:00Z"
    }
]

Обновление перекрытия дороги

Чтобы обновить время перекрытия, отправьте PATCH-запрос на endpoint /restrictions/{id}, где {id} — UUID перекрытия.

Тело запроса должно содержать JSON-объект со следующими атрибутами:

start_time — дата и время начала перекрытия в формате RFC 3339 (например, 2020-05-15T15:52:01Z).
end_time — дата и время окончания перекрытия в формате RFC 3339 (например, 2020-05-15T15:52:01Z).

{
    "start_time": "2022-03-01T12:00:00Z",
    "end_time": "2022-04-01T12:00:00Z"
}

Удаление перекрытия дороги

Чтобы удалить перекрытие, отправьте DELETE-запрос на endpoint /restrictions/{id}, где {id} — UUID перекрытия.

В случае успеха, перекрытие будет отмечено как удалённое и более не будет учитываться при построении маршрутов. Все перекрытия, удалённые таким способом, а также перекрытия с истёкшей датой окончания, будут удалены из базы данных в рамках ближайшего цикла очистки.

Зависимости

Подробнее о том, как проверить требования для каждого сервиса, см. в документе Системные требования.

Для Navi-Castle
- Общая инфраструктура:
  - Поддержка Kubernetes Persistent Volume и динамических Persistent Volume Claim для хранения данных (необязательно).
    
    Важное примечание:
    
    Настоятельно рекомендуется настроить функциональность Persistent Volume и Persistent Volume Claim в вашем кластере Kubernetes.
    
    Без этой функциональности Navi-Castle будет хранить необходимые для работы сервисов навигации данные в разделе emptyDir. Это означает, что если под (pod) Navi-Castle удаляется, том типа emptyDir также удаляется, и все данные пропадают. Для запуска потребуется новый импорт данных из S3-хранилища при старте пода.
Для Navi-Back
- Сервисы:
  - Прокси для API пробок, настроенный на использование серверов обновлений, предоставляющих данные о пробках в формате, который подходит для использования сервисами навигации.
  - Navi-Castle
  - Сервис лицензий.
  - Сервис API-ключей.
Для Navi-Router
- Сервисы:
  - Navi-Castle
Для Navi-Front
- Сервисы:
  - Navi-Castle
  - Navi-Router
  - Navi-Back
Для Distance Matrix Async API
- Общая инфраструктура:
  - Хранилище PostgreSQL
  - S3-совместимое хранилище
  - Брокер сообщений Apache Kafka
- Сервисы:
  - Navi-Castle
  - Navi-Back
Для Restrictions API
- Общая инфраструктура:
  - PostgreSQL для хранения данных о перекрытиях дорог. Необходимо установить PostgreSQL с включённым PL/pgSQL.
- Сервисы:
  - Navi-Castle
  - Navi-Back

Что дальше?

Узнайте, как установить или обновить сервис:
- Установка сервисов навигации
- Обновление сервисов навигации
Узнайте больше о программном комплексе 2ГИС:
- Архитектура программного комплекса 2ГИС
- Системные требования