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

В этой статье описывается, как установить и настроить сервисы навигации в вашем окружении. Чтобы узнать, как использовать 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 получает входящий запрос:
1. Он передает этот запрос сервису Navi-Router.
2. Navi-Router использует тот же файл правил, что и Navi-Back, и получает все данные от Navi-Castle. Пользуясь этим файлом и имеющимися данными, Navi-Router выполняет маршрутизацию: находит правило, под которое попадает запрос. Другими словами, Navi-Router определяет, существует ли инстанс Navi-Back, который может обработать этот запрос.
  
  Если запрос успешно проходит проверку в сервисе ключей и существует подходящее для его обработки правило, то Navi-Router отправляет название этого правила Navi-Front.
3. Navi-Front находит подходящий инстанс Navi-Back, который настроен на работу с правилом, название которого вернул Navi-Router, и передает запрос этому инстансу.
4. Инстанс Navi-Back обрабатывает запрос и возвращает ответ Navi-Front.
5. 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ГИС:
- Архитектура программного комплекса 2ГИС
- Системные требования