Навигация
Сервисы навигации позволяют строить маршруты, а также получать информацию о расстоянии и времени в пути между точками на карте. Все это может делаться с учётом или без учёта текущей ситуации с пробками на дорогах.
В этой статье описывается, как установить и настроить сервисы навигации в вашем окружении. Чтобы узнать, как использовать 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
сNavi-Back
описано в разделе Обработка асинхронных запросов к Distance Matrix API.Restrictions API
— предоставляет информацию о перекрытиях дорог. Подробнее см. в разделе Restrictions API.
Также используется прокси для API пробок для получения данных о пробках в реальном времени с серверов 2ГИС. Navi-Back использует эту информацию для построения маршрутов с учётом трафика.
Сервисы навигации используют масштабируемую архитектуру, что позволяет с легкостью распределять обработку входящих запросов между несколькими инстансами 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.
Обработка асинхронных запросов к Distance Matrix API
Чтобы реализовать поддержку асинхронной версии Distance Matrix API, необходимой для расчёта большого количества точек, нужно установить сервис Distance Matrix Async API. Этот сервис является фронтендом к сервису Navi-Back, взаимодействие с которым ведётся с помощью S3-совместимого хранилища и событий в Apache Kafka. Чтобы определить, какой именно инстанс Navi-Back сможет обработать тот или иной запрос, сервис использует данные, загруженные с сервиса Navi-Castle.
Запросы пользователей выполняются асинхронно. После отправки запроса к сервису пользователь должен периодически отправлять дополнительные запросы для получения информации о статусе его выполнения. Информация о состоянии запросов хранится в PostgreSQL.
Порядок обработки запроса выглядит так:
-
Пользователь отправляет запрос.
-
Сервис Distance Matrix Async API сохраняет данные запроса в хранилище S3.
-
Сервис Distance Matrix Async API создаёт событие в Apache Kafka. Чтобы определить, в какой именно топик Apache Kafka нужно направить событие, сервис использует данные, заранее загруженные с сервиса Navi-Castle, а также правила, указанные в настройке
topicRules
.Если пользователь запросит статус выполнения запроса в этот момент, он получит информацию о том, что запрос ещё выполняется.
-
Один из инстансов Navi-Back читает событие из Apache Kafka, загружает данные запроса из хранилища S3 и производит необходимые вычисления. После успешного или неуспешного завершения работы он создаёт новое событие в топике, указанном в настройке
consumerCancelTopic
, при необходимости записав результаты вычислений в хранилище S3. -
Сервис Distance Matrix Async API читает событие из Apache Kafka и при необходимости загружает данные ответа из хранилища S3.
Если пользователь запросит статус выполнения запроса в этот момент, он получит информацию о том, что запрос выполнен, а также результат его выполнения.
В некоторых случаях сервис может прервать выполнение запроса, уже отправленного в Navi-Back. Для этого он создаёт события в топиках, указанных в настройках consumerTaskTopic
и consumerCancelTopic
.
Restrictions API
С помощью сервиса Restrictions API вы можете работать с информацией о перекрытиях дорог: получать список активных перекрытий, добавлять новые перекрытия и удалять более не актуальные. Все перекрытия, добавленные через Restrictions API, учитываются при построении маршрутов.
Сервис Restrictions API предоставляет RESTful API для использования в клиентском приложении.
Сервис Restrictions API взаимодействует с сервисами (Navi-Castle и Navi-Back) для получения географических данных. В том числе сервис использует cron-задачу для периодического (раз в час) получения текущей информации о перекрытиях дорог от сервиса Navi-Castle.
Добавление перекрытия дороги
Чтобы добавить перекрытие дороги, отправьте POST-запрос на эндпоинт /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-запрос на эндпоинт /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-запрос на эндпоинт /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-запрос на эндпоинт /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ГИС: