Архитектура API Яндекс Метрики и взаимодействие с ней

Чтобы стабильно работать с API Метрики, нужно понимать не только «какой метод вызвать», но и как устроен контур: OAuth-приложение -> токен -> права на счётчик -> выбор API -> лимиты и обработка ошибок. Ниже -- схема взаимодействия для директолога и разработчика.

← Каталог: Метрика · Введение · Системы аналитики · Счётчик и код · Безопасность данных · Основы HTML/JS · Карта настройки · Типы целей · Цели · Автоцели и ecommerce · ЯТМ на практике · Тег Менеджер · Фильтры и операции · Доступы и роли · Вебвизор и карты · Карты и формы · Семплирование · Отчёты · Стандартные отчёты · Атрибуция · Сегментация · Офлайн-конверсии · ClientID и идентификаторы · Measurement Protocol · CRM и интеграции · Битрикс24 и Albato · Мессенджеры · Воронки · AppMetrica · API: введение · API: возможности · API: окружение · API: отчёты на практике · API: Logs · DataLens · Чек-лист · Справка Яндекс Метрики

Содержание

1. Общая схема
2. OAuth и скоупы
3. Счётчик как единица доступа
4. Синхронное взаимодействие: Reports
5. Асинхронное взаимодействие: Logs
6. Импорт: как данные входят в Метрику
7. Ошибки и безопасность
8. Рекомендуемая архитектура для агентства

Общая схема

Упрощённый поток:

1. Регистрируете OAuth-приложение на oauth.yandex.ru (тип «для доступа к API»).
2. Запрашиваете токен от имени пользователя, у которого есть доступ к счётчику.
3. Клиент (скрипт, ETL, AdPump/BI) шлёт HTTPS-запросы на api-metrika.yandex.net.
4. Management/Stat отвечают JSON сразу; Logs -- через заявку и скачивание файлов.
5. Данные уходят в хранилище / дашборд / обратно в Директ как офлайн-конверсии.

OAuth и скоупы

Токен передаётся в каждом запросе:

Authorization: OAuth <access_token>

Основные доступы приложения:

Пошагово: быстрый старт -> OAuth.

Счётчик как единица доступа

Почти все методы привязаны к counterId. Сначала получают список:

GET https://api-metrika.yandex.net/management/v1/counters
Authorization: OAuth ...

Типы доступа на стороне Метрики (владелец / гость просмотр / гость редактирование) должны соответствовать операции. Для записи целей и импорта офлайна обычно нужен edit.

Практика ролей: Доступы и роли в Метрике.

Синхронное взаимодействие: Reports

Типовой запрос отчёта:

GET https://api-metrika.yandex.net/stat/v1/data?ids=COUNTER_ID&metrics=ym:s:visits,ym:s:goal%3Cgoal_id%3Ereaches&dimensions=ym:s:date&date1=2026-07-01&date2=2026-07-31
Authorization: OAuth ...

Ответ -- JSON с массивами data / totals. Ошибки квот и неверных метрик возвращаются сразу -- удобно для cron-дашбордов.

Асинхронное взаимодействие: Logs

Схема Logs API:

1. POST .../logrequests -- создать заявку (поля visits/hits, даты);
2. GET .../logrequest/{requestId} -- статус (created -> processed_failed / processed);
3. GET .../part/{N}/download -- скачать TSV/части;
4. POST .../clean -- освободить слот.

Дальше данные обычно грузят в ClickHouse / BigQuery и уже там строят атрибуцию.

Импорт: как данные входят в Метрику

Офлайн-конверсии и CRM-заказы передаются с идентификаторами визита/клиента (ClientID, PurchaseID, телефоны/email в разрешённых форматах -- по правилам метода). После загрузки Метрика пытается привязать событие к визиту; статус привязки можно контролировать в отчётах (см. обновления 2026).

Инструкция: Офлайн-конверсии.

Ошибки и безопасность

Храните токены в секретах, не в репозитории. Для агентства -- отдельные приложения или чёткое разделение клиентских доступов.

Рекомендуемая архитектура для агентства

1. Scheduler (cron) -- ежедневные Reports по ключевым счётчикам.
2. Token vault -- OAuth refresh/перевыпуск без хардкода.
3. Import worker -- CRM -> Data Import (офлайн-конверсии) раз в N часов.
4. Optional Logs ETL -- только для клиентов с DWH.
5. Alerting -- падение целей / ошибка 403 -> чат команде.

Параллельно с API Директа: серия API Директа.

Чек-лист внедрения

1. Создать OAuth-приложение и выписать скоупы
2. Проверить доступ аккаунта токена к боевому счётчику
3. Сделать тестовый GET /counters и один stat/v1/data
4. Настроить секреты и ротацию токена
5. Если нужен офлайн -- отдельный worker Data Import с мониторингом ошибок

Комментарий эксперта

Роман Скороходов «Директ — мой вайб» Руководитель отдела контекстной рекламы Monster Context, рекомендованный специалист Яндекса. Главная ошибка -- сразу лезть в Logs «потому что круто». Сначала стабилизируйте Reports и офлайн-импорт: это то, что реально двигает CPA в Директе. Архитектуру DWH имеет смысл строить, когда данные уже чистые.

Частые вопросы

Чем API Метрики отличается от API Директа?
Метрика -- поведение на сайте, цели, офлайн; Директ -- кампании, ставки, расходы рекламы. Для полной картины нужны оба.

Можно ли одним токеном ходить во все счётчики агентства?
Только в те, куда выдан доступ аккаунту-владельцу токена. Иначе -- отдельные гостевые доступы или токены.

Reports или Logs -- что выбрать?
95% задач директолога закрывает Reports + Data Import. Logs -- когда нужна своя атрибуция или сырые поля.

Обзор возможностей: Возможности API Метрики. Дальше по практике: выбор окружения и готовые запросы Reports API. Официально: yandex.ru/dev/metrika.

Материал подготовлен редакцией AdPump совместно со специалистами Monster Context (m-context.ru) на основе практики ведения аккаунтов Яндекс Директа и обновлений Яндекс Метрики 2026 года.

← Каталог: Метрика · Введение · Системы аналитики · Счётчик и код · Безопасность данных · Основы HTML/JS · Карта настройки · Типы целей · Цели · Автоцели и ecommerce · ЯТМ на практике · Тег Менеджер · Фильтры и операции · Доступы и роли · Вебвизор и карты · Карты и формы · Семплирование · Отчёты · Стандартные отчёты · Атрибуция · Сегментация · Офлайн-конверсии · ClientID и идентификаторы · Measurement Protocol · CRM и интеграции · Битрикс24 и Albato · Мессенджеры · Воронки · AppMetrica · API: введение · API: возможности · API: окружение · API: отчёты на практике · API: Logs · DataLens · Чек-лист