Подключение сервиса маршрутизации укладывается в пять шагов: аккаунт и биллинг, сервисный аккаунт с ролью, API-ключ, квоты по запросам, тестовый вызов. При готовой инфраструктуре весь путь занимает 30-60 минут.
Сразу про границу проверенных данных. В источниках, доступных на момент подготовки статьи, нет подтверждённых сведений о Яндекс Маршрутизации: ни методов API, ни тарифов, ни квот, ни цен. Поэтому порядок ниже построен как рабочий шаблон подключения API-сервиса маршрутизации, а имена методов, лимит точек в запросе и суммы сверяйте в консоли Яндекс Облака и официальной документации. Проверенные практики по серверному окружению, секретам и версиям API подкреплены ссылками на доступные источники.
Перед запуском в продакшене сверьте в консоли тариф, квоты и формат запроса. Лимиты и цены меняются чаще, чем обновляются публичные материалы.
Что такое Яндекс Маршрутизация и кому она нужна
Сервис маршрутизации решает прикладную задачу: по набору координат вернуть путь, расстояние и время в пути. Доступ дают двумя способами - через программный API для сервисов и через консоль для ручных проверок. В логистике это расчёт ETA для заказов, в такси - построение трека, в планировании рейсов - оценка времени между складами.
Ключевые возможности и ограничения
Сервисы такого класса закрывают четыре группы задач: маршрут между двумя и более точками, расчёт с учётом пробок и дорожной обстановки, матрицы расстояний и времени для набора точек, изохроны - зоны, достижимые за заданное время. Матрицы и изохроны обычно открывают на расширенном тарифе.
Ограничения проверяйте до старта: максимальное число точек в одном запросе, список поддерживаемых регионов, набор профилей транспорта (легковой, грузовой, пешеходный), глубина прогноза пробок. Для Яндекс Маршрутизации конкретные значения смотрите в консоли: в доступных источниках их нет.
Кому подходит сервис: сценарии для DevOps и сисадминов
Три типовых сценария. Логистика внутри микросервисов: сервис заказов отправляет координаты и получает ETA, который уходит в клиентское приложение. Балансировка нагрузки с учётом геолокации: ближайший склад или курьер выбирается по матрице расстояний. Мониторинг маршрутов: регулярный пересчёт трека и алерт при отклонении.
GIS-экспертиза для подключения не нужна. Хватает HTTP-клиента, ключа и умения читать JSON. Смежная тема - маршрутизация процессов в Nginx, Traefik и Kubernetes Ingress, если маршруты нужно строить не только по карте, но и внутри инфраструктуры.
Подготовка окружения перед подключением
Чек-лист до первого запроса: аккаунт в облаке, доступ к консоли, права администратора, активный биллинг и исходящий HTTPS на 443. Сервисный аккаунт заводите сразу, а не тянете интеграцию под личным.
Требования к серверу и сети
Клиенту хватает 1 vCPU и 512 МБ ОЗУ: он формирует HTTP-запросы и разбирает JSON. Главное требование - исходящий доступ по 443 к хосту API. Проверьте связность до настройки ключей, чтобы потом не искать сетевую проблему в коде.
nc -vz $ROUTING_API_HOST 443
curl -sS -o /dev/null -w "%{http_code}\n" https://$ROUTING_API_HOST/
За прокси передайте его в curl явно или добавьте хост API в исключения:
curl -x http://proxy.local:3128 -sS https://$ROUTING_API_HOST/
Ресурсы сервера проще масштабировать в облаке: там вы выбираете число процессоров, объём ОЗУ, хранилище и ОС, а увеличиваете или уменьшаете их через портал без миграции на новую машину. Такую модель описывает разбор облачного хостинга от Hostwinds. Если сервер под клиента ещё не поднят, облачную инфраструктуру с VDS/VPS, базами данных и Kubernetes разворачивают через Timeweb Cloud.
Создание сервисного аккаунта и ролей
- Войдите в консоль облака под учётной записью администратора.
- Откройте раздел сервисных аккаунтов и создайте новый.
- Назначьте роль. Для старта подойдёт editor, для продакшена соберите кастомную роль только с правами на маршрутизацию.
- Сохраните идентификатор сервисного аккаунта: он понадобится при выпуске ключа.
Принцип минимальных прав экономит нервы при разборе инцидентов: если ключ утечёт, зона поражения ограничится маршрутизацией.
Получение API-ключа и настройка доступа
Создание API-ключа в консоли
- Раздел «Сервисные аккаунты», выберите нужный аккаунт.
- Нажмите «Создать новый ключ» и выберите тип «API-ключ».
- Скопируйте ключ.
Ключ показывается один раз. Закрыли окно, не сохранив копию, выпускайте новый и удаляйте старый. Ключ состоит из идентификатора и секрета: в заголовке авторизации передаётся пара, а секрет восстановлению не подлежит.
Настройка переменных окружения и секретов
export YANDEX_ROUTING_API_KEY="<ваш-ключ>" # или через systemd EnvironmentFile / .env
Для продакшена держите ключ в секретах Kubernetes, HashiCorp Vault или облачном секрет-менеджере. Базовое правило для любого API: свой ключ на сервис и хранение в защищённом хранилище секретов. Эту практику прямо описывает документация API Polytranslator: отдельный ключ для приложения, ключ идемпотентности на каждый запрос и хранение секрета вне кода.
Ключ идемпотентности полезен и здесь: повторная отправка того же запроса при сетевом таймауте не должна приводить к двойному списанию квоты.
Выбор тарифного плана и настройка квот
Цены и включённые объёмы запросов сверяйте в консоли: подтверждённых цифр по Яндекс Маршрутизации в доступных источниках нет. Ниже - критерии выбора и порядок работы с квотами.
Сравнение тарифных планов
| Параметр | Базовый | Расширенный | Корпоративный |
|---|---|---|---|
| Назначение | Тесты и пилоты | Продакшен средней нагрузки | Высокие нагрузки и SLA |
| Объём запросов | Минимальный, часть бесплатно | Пакеты по факту потребления | Индивидуально, договор |
| Функции | Базовый маршрут | Матрицы, изохроны | Полный набор, приоритет обработки |
| Поддержка и SLA | Стандартная | Приоритетная | Выделенный контакт, SLA |
| Цена | Уточняйте в консоли | Уточняйте в консоли | По запросу |
Значения ориентировочные: перед покупкой сверьте их в биллинге. Базовый тариф берите для проверки интеграции, расширенный - когда есть стабильный трафик, корпоративный - когда нужны гарантии по доступности и предсказуемый счёт.
Установка и изменение квот
Квоты бывают мягкими и жёсткими. Мягкую можно превысить с уведомлением, жёсткая отклоняет запросы. Порядок в консоли: раздел «Квоты», выберите сервис маршрутизации, измените значение. Часть квот поднимают только через поддержку, поэтому закладывайте запас заранее.
Пример контроля расходов: поставьте суточный лимит 5000 запросов. При зацикленном клиенте вы получите 429 и уведомление, а не счёт на порядок больше ожидаемого. Перед дорогими операциями задавайте предельную стоимость запроса до его выполнения, как это описано у Polytranslator: проверьте баланс и лимит стоимости заранее.
Проверка соединения и первые запросы
Тестовый запрос через curl
curl -X POST "https://$ROUTING_API_HOST/v1/route" \
-H "Authorization: Api-Key $YANDEX_ROUTING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"points": [
{"lat": 55.75, "lon": 37.61},
{"lat": 59.93, "lon": 30.33}
]
}'
Показан вызов на две точки: Москва и Санкт-Петербург. Точный путь и формат тела возьмите из консоли. В ответе ожидайте JSON с геометрией маршрута, расстоянием и временем в пути. Первый вызов делайте из той же сети, где будет работать клиент: так вы отделите проблемы доступа от проблем приложения.
Интерпретация ответов и кодов ошибок
| Код | Что значит | Что делать |
|---|---|---|
| 200 | Успех | Проверьте поля расстояния и времени в теле ответа |
| 400 | Неверный запрос | Проверьте JSON, типы полей и порядок координат |
| 401 | Неверный или отсутствующий ключ | Сверьте заголовок авторизации и значение переменной окружения |
| 403 | Недостаточно прав | Назначьте сервисному аккаунту нужную роль |
| 429 | Превышена квота | Поднимите лимит или включите повтор с задержкой |
| 5xx | Ошибка на стороне сервиса | Повторите с экспоненциальной задержкой, проверьте статус сервиса |
Типовые проблемы при подключении и их решения
Большинство сбоев на старте сводится к нескольким сценариям. Для каждого - симптом, причина и действие.
Ошибки аутентификации и авторизации
- 401 Unauthorized. Ключ неверный, истёк или не передан. Проверьте заголовок авторизации и что переменная окружения не пустая.
- 403 Forbidden. У сервисного аккаунта нет роли. Назначьте editor или кастомную роль с правами на маршрутизацию.
Проблемы с сетью и прокси
- Таймаут. Хост API недоступен или блокируется. Проверьте 443 через nc или telnet и настройте исключение в прокси.
- Connection refused. Прокси перехватывает трафик. Передайте прокси явно через --proxy либо задайте исключение.
Прочие частые случаи: 400 из-за неверного формата JSON, 429 при превышении квоты, 404 или 410 при обращении к устаревшей версии API. Версионирование по годам встречается регулярно, и старые версии выводят из обслуживания: API 5e-srd-api версионируется по годам выпуска SRD, и на момент описания открыта только одна версия (README 5e-srd-api). Фиксируйте версию в URL и в конфиге клиента, чтобы обновление не застало врасплох.
Как читать логи и трассировки при зацикливании и 404 в веб-слое, разобрано в материале про диагностику проблем маршрутизации и в руководстве по типовым ошибкам маршрутизации.
Особенности настройки в серверных и облачных сценариях
Настройка на выделенном сервере
На физической машине вы отвечаете за сеть и безопасность сами: правила исходящего трафика, корневые сертификаты, отдельный пользователь для запуска клиента, systemd-юнит для автозапуска. Выделенный сервер даёт полный контроль над железом: каждое ядро ЦП, каждый ГБ ОЗУ и каждый байт памяти в вашем распоряжении, что даёт максимальную производительность и физическую изоляцию, как описывает сравнение облачного и выделенного хостинга.
Практика: запускайте клиент под непривилегированным пользователем, ограничьте исходящие соединения только хостом API и включите логирование кодов ответа.
Интеграция с облачными платформами
В облаке доступ к сервисам выдают через роли и сервисные аккаунты, а не через статические ключи на диске. В Яндекс Облаке это IAM-роли, в AWS - IAM-роли для EC2, в GCP - сервисные аккаунты с временными токенами из metadata-сервиса. Облачный сервер остаётся изолированной виртуальной средой, в ресурсы которой вносят вклад несколько физических машин: описание облачной модели.
В Kubernetes ключ кладут в Secret, а доступность API проверяют init-контейнером до старта основного приложения. Так сбой сети не превращается в череду падений пода.
Что делать после подключения: мониторинг и оптимизация
Ключевые метрики для отслеживания
Четыре метрики закрывают почти все риски: RPS, задержка на 95-м перцентиле, доля ошибок и расход квоты. Ориентиры для алертов: ошибки выше 1%, задержка p95 выше 500 мс, расход квоты выше 80% от лимита. Пороговые значения подстройте под свой SLA.
Сбор метрик строят на Prometheus и Grafana, а для распределённых систем добавляют трассировки: подробнее в материале про наблюдаемость в service mesh.
Оптимизация запросов и расходов
Главный рычаг - батчинг. Если тариф считает запросы, а не точки, объединение 100 точек в один вызов вместо 100 отдельных сокращает расход до 100 раз. Учитывайте лимит точек в запросе и добавляйте кэш для повторяющихся маршрутов.
Второй рычаг - периодический пересмотр тарифа: при стабильном росте трафика переход на пакетный план обычно дешевле переплаты по базовому. Раз в месяц сверяйте фактическое потребление с прогнозом.
Настройте алерт на 429 и на долю ошибок выше 1% в тот же день, когда подключили ключ. Это дешевле, чем разбирать ночной инцидент с исчерпанной квотой.