Сервисы навигации

Сервисы навигации позволяют строить маршруты и получать информацию о расстоянии и времени в пути между точками на карте с учётом пробок или без (в зависимости от конфигурации).

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

Архитектура

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

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

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

• Distance Matrix Async API — рассчитывает матрицы расстояний для большого количества точек в асинхронном режиме. Подробную схему взаимодействия сервисов в этом сценарии см. в разделе Обработка асинхронных запросов к Distance Matrix API.
• TSP API — строит кратчайший маршрут обхода точек. Подробную схему взаимодействия сервисов в этом сценарии см. в разделе Решение задачи коммивояжёра.
• Restrictions API — позволяет добавлять собственную информацию о дорожных перекрытиях. Подробнее см. в разделе Работа с дорожными перекрытиями.
• Прокси для API пробок — предоставляет данные о пробках в реальном времени с серверов 2ГИС. Navi-Back использует эту информацию для построения маршрутов с учётом трафика. Подробнее см. в инструкции Установка прокси для 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 получает входящий запрос:

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.

• В зависимости от ваших требований, вы также можете пропустить установку сервиса TSP API, Restrictions API и прокси для API пробок.

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

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

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

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

1. Пользователь отправляет запрос к Distance Matrix Async API в формате REST или gRPC. Если используются gRPC-запросы, сервис Navi Async gRPC proxy преобразует их в формат REST.

2. Сервис Distance Matrix Async API разделяет запрос на подзапросы и сохраняет данные в хранилище S3.

3. Сервис Distance Matrix Async API создаёт событие в Apache Kafka. Чтобы определить, в какой именно топик Apache Kafka нужно направить событие, сервис использует данные, заранее загруженные с сервиса Navi-Castle, а также правила, указанные в настройке topicRules.

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

4. Один из инстансов Navi-Attractor читает событие из Apache Kafka, загружает данные запроса из хранилища S3 и производит «притяжку» точек запроса к графу. После успешного или неуспешного завершения работы Navi-Attractor создаёт новое событие в топике, записав результаты вычислений в хранилище S3.

5. Сервис Distance Matrix Async API читает событие о «притяжке», получает результаты вычислений из S3, создаёт задание для Navi-Back, отправляет оповещение о задании в Apache Kafka.

6. Один из инстансов Navi-Back читает событие из Apache Kafka, загружает данные запроса из хранилища S3 и производит необходимые вычисления. После успешного или неуспешного завершения работы он создаёт новое событие в топике, указанном в настройке consumerCancelTopic, при необходимости записав результаты вычислений в хранилище S3.

7. Сервис Distance Matrix Async Merger соединяет ответы всех подзапросов в один ответ и сохраняет результат в хранилище S3.

8. Сервис 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, чтобы получить матрицу расстояний для всех возможных пар точек, а затем выбирает наиболее оптимальную комбинацию этих расстояний для решения задачи.

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

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

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

Работа с дорожными перекрытиями

Вы можете работать с дорожными перекрытиями только одним из способов:

• Использовать информацию о перекрытиях из поставляемых данных 2ГИС. В этом случае устанавливать Restrictions API не нужно.
• Установить Restrictions API и добавлять собственную информацию о перекрытиях. В этом случае для построения маршрутов будут использоваться только добавленные перекрытия. Сервис Restrictions API взаимодействует с сервисами Navi-Castle и Navi-Back для получения географических данных, а также предоставляет RESTful API.

Важно

Одновременное использование сервиса Restrictions API (параметр cron.enabled.restriction) и поставляемых данных (параметр cron.enabled.restrictionImport) в конфигурационном файле для Navi-Castle приведёт к некорректной работе.

Пример конфигурационного файла для использования поставляемых данных:

values-castle.yaml

...

cron:
  enabled:
    import: true
    restriction: false // Cервис navi-restrictions
    restrictionImport: true // Поставляемые данные
  schedule:
    import: 11 * * * *
    restriction: "*/5 * * * *"
    restrictionImport: "*/5 * * * *"

...

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

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

В теле запроса передайте JSON с необходимыми параметрами:

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

Где:

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

Если перекрытие добавлено, ответ будет содержать его UUID.

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

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

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

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

Где:

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

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

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

В теле запроса передайте JSON с необходимыми параметрами:

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

Где:

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

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

Чтобы удалить дорожное перекрытие, отправьте 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-Attractor.
    • Navi-Back.
    • Navi-Router (для базовых API).
    • Navi-Front (для базовых API).
    • Navi-Splitter (для синхронного Distance Matrix API).

• Для Navi-Attractor

  • Сервисы:

    • Navi-Castle.
    • Navi-Back.
    • Navi-Router (для базовых API).
    • Navi-Front (для базовых API).
    • Navi-Splitter (для синхронного Distance Matrix API).

• Для Navi-Back

  • Сервисы:

    • Сервис лицензий.
    • Сервис сбора статистики.
    • Navi-Castle.
    • Navi-Attractor.
    • Navi-Router (для базовых API).
    • Navi-Front (для базовых API).
    • Navi-Splitter (для синхронного Distance Matrix API).
    • Прокси для API пробок (необязательно, только для получения онлайн-данных о пробках). Сервис должен использовать серверы обновлений, которые предоставляют данные о пробках в формате, подходящем для сервисов навигации.

• Для Navi-Router

  • Сервисы:

    • Сервис API-ключей.
    • Navi-Castle.
    • Navi-Attractor.
    • Navi-Back.
    • Navi-Front.
    • Navi-Splitter (для синхронного Distance Matrix API).

• Для Navi-Front

  • Сервисы:

    • Navi-Castle.
    • Navi-Attractor.
    • Navi-Back.
    • Navi-Router.
    • Navi-Splitter (для синхронного Distance Matrix API).

• Для Distance Matrix Async API

  • Общая инфраструктура:

    • S3-совместимое хранилище.
    • PostgreSQL.
    • Брокер сообщений Apache Kafka.

  • Сервисы:

    • Navi-Castle.
    • Navi-Attractor.
    • Navi-Back.
    • Navi Async gRPC proxy (если запросы к Distance Matrix Async API будут приходить в формате gRPC).
    • Distance Matrix Async API.

• Для TSP API

  • Общая инфраструктура:

    • S3-совместимое хранилище.
    • PostgreSQL.
    • Брокер сообщений Apache Kafka.

  • Сервисы:

    • Сервис API-ключей.
    • Navi-Castle.
    • Navi-Attractor.
    • Navi-Back.
    • VRP Task Manager.
    • VRP Solver.
    • Distance Matrix Async API.

• Для Restrictions API

  • Общая инфраструктура:

    • PostgreSQL с включённым PL/pgSQL для хранения данных о перекрытиях дорог.

  • Сервисы:

    • Сервис API-ключей.
    • Navi-Castle.
    • Navi-Attractor.
    • Navi-Back.
    • Navi-Restrictions.

Что дальше?

• Узнайте, как установить или обновить сервис:

  • Установка сервисов навигации
  • Обновление сервисов навигации

• Узнайте больше о программном комплексе 2ГИС:

  • Архитектура программного комплекса 2ГИС
  • Системные требования