API навигации | On-Premise | 2GIS Documentation
On-Premise
Личный кабинет

Навигация

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

В этой статье описывается, как установить и настроить сервисы навигации в вашем окружении. Чтобы узнать, как использовать 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 Async API. Этот сервис является фронтендом к сервису Navi-Back, взаимодействие с которым ведётся с помощью S3-совместимого хранилища и событий в Apache Kafka. Чтобы определить, какой именно инстанс Navi-Back сможет обработать тот или иной запрос, сервис использует данные, загруженные с сервиса Navi-Castle.

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

Архитектура сервиса Distance Matrix API

Порядок обработки запроса выглядит так:

  1. Пользователь отправляет запрос.

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

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

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

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

  5. Сервис Distance Matrix Async API читает событие из Apache Kafka и при необходимости загружает данные ответа из хранилища S3.

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

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

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

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

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

Архитектура сервиса Restrictions API

Чтобы добавить перекрытие дороги, отправьте 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

Что дальше?