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.

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

  • Для Navi-Castle

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

      • Поддержка Kubernetes Persistent Volume и динамических Persistent Volume Claim для хранения данных (необязательно).

        Важное примечание:

        Настоятельно рекомендуется настроить функциональность Persistent Volume и Persistent Volume Claim в вашем кластере Kubernetes.

        Без этой функциональности Navi-Castle будет хранить необходимые для работы сервисов навигации данные в разделе emptyDir. Это означает, что если под (pod) Navi-Castle будет убран с узла (node) кластера Kubernetes, на котором он выполняется, то эти данные будут потеряны.

  • Для Navi-Back

    • Сервисы:

      • Прокси для API пробок, настроенный на использование серверов обновлений, предоставляющих данные о пробках в формате, который подходит для использования сервисами навигации.
      • Navi-Castle
  • Для Navi-Router

    • Сервисы:

      • Navi-Castle
  • Для Navi-Front

    • Сервисы:

      • Navi-Castle
      • Navi-Router
      • Navi-Back
  • Для Distance Matrix Async API

    • Сервисы:

      • Navi-Castle
      • Navi-Back
    • Общая инфраструктура:

      • Хранилище PostgreSQL
      • Хранилище S3
      • Брокер сообщений Apache Kafka
  • Для Restrictions API

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

      • PostgreSQL для хранения данных о перекрытиях дорог. Необходимо установить PostgreSQL 12 с включённым PL/pgSQL.
    • Сервисы:

      • Navi-Castle
      • Navi-Back

Navi-Back использует файл правил, чтобы указать, какие типы запросов он может обрабатывать. Это позволяет инстансу Navi-Back запрашивать и хранить минимальный набор данных от Navi-Castle, достаточный для обработки указанных типов запросов.

Файл также используется Navi-Router для определения того, какой из нескольких инстансов Navi-Back может обработать запрос.

Файл правил имеет следующую структуру:

[
  {
    "name": "<имя правила>",
    "router_projects": [
        "<имя проекта для Navi-Router>"
    ],
    "moses_projects": [
        "<имя проекта для Navi-Back>"
    ],
    "projects": [
        "<имя региона>"
    ],
    "queries": [
        <массив типов запросов, которые разрешено обрабатывать>
    ],
    "routing": [
        <массив типов маршрутизации, которые разрешено обрабатывать для запросов на построение маршрута>
    ]
  }
]

Примечание:

Построение маршрутов для экстренных служб (значение emergency в массиве routing) поддерживается, только если при установке Navi-Back была задана настройка naviback.simpleNetwork.emergency: true.

Чтобы реализовать поддержку асинхронной версии 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 перекрытия.

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

Что дальше?