Две поверхности: приём событий и основной API
У ActionPulse два независимых HTTP-сервиса с разными базовыми адресами, портами и типами ключей. Что куда отправлять, чем это ограничено и как проверить, что оба живы.
На этой странице
У ActionPulse два независимых HTTP-сервиса. События уходят на один адрес,
а отчёты, ключи, настройки и выгрузки читаются с другого. Это первое, что стоит
понять перед первым запросом: значительная часть непонятных 401 и 404
в начале интеграции — это запрос, ушедший не на ту поверхность или с ключом
не того типа.
Полный машинный перечень методов — в справочнике API: всего
214 операций в 29 разделах, у каждой указаны
поверхность, схема аутентификации, параметры и коды ответов. Эта страница
объясняет то, чего в машинной спецификации нет: зачем поверхностей две и как
не перепутать их.
Почему сервисов два
Приём событий (data plane) делает одно: принимает данные, проверяет их,
складывает в очередь и отвечает 202. К аналитическому
хранилищу он не обращается вообще. В отчётах событие появляется позже, когда
его разберёт фоновая обработка.
Основной API (control plane) — всё остальное: вход и сессии, организация и участники, проекты, ключи приёма, отчёты, панели, реестр событий, уведомления, импорты, выгрузки, удаление данных, биллинг в облаке и лицензия в собственной установке.
Разделение сделано не для красоты архитектурной схемы, а по трём практическим причинам:
- Разная публичность. Приём вызывает браузер каждого посетителя вашего сайта — публичным токеном, с домена из списка этого токена. Основной API вызывают только кабинет, ваш бэкенд и ваш CI/CD.
- Разная нагрузка. Приём — это поток мелких запросов, основной API — редкие тяжёлые. Они масштабируются по отдельности.
- Разные отказы. Если аналитическое хранилище недоступно, приём продолжает принимать события в очередь и ничего не теряет. Обратное тоже верно: отчёты читаются, даже когда приём остановлен.
Базовые адреса и порты
| Основной API | Приём событий | |
|---|---|---|
| Базовый адрес | https://YOUR_ACTIONPULSE_HOST/api/v1 |
https://YOUR_ACTIONPULSE_INGEST_HOST |
| Пути | всё под /api/v1 |
/v1/… |
| Порт процесса | 8080 |
8081 |
| Кто вызывает | кабинет, ваш бэкенд, CI/CD | браузер посетителя, ваш бэкенд |
| Ключ | токен доступа пользователя | ключ приёма проекта |
| Раздел справочника | все разделы, кроме /api/ingest/ |
/api/ingest/ |
Порты — это то, что слушают сами процессы внутри установки. Публичные адреса
задаёт развёртывание: перед сервисами обычно стоит прокси с TLS, и снаружи
каждый доступен по своему адресу. В собственной установке публичный адрес приёма
задаётся переменной окружения PUBLIC_INGEST_URL.
Два пути вне /api/v1
Почти все методы основного API лежат под /api/v1, но два пути смонтированы
в корне сервиса и под этот префикс не попадают:
/healthz— служебная проверка живости; она же есть у приёма;- разбор публичной ссылки-шеринга — анонимная граница, привязанная к токену самой ссылки.
Пути приёма /v1/… под /api/v1 не лежат тем более: они обслуживаются
другим сервисом по другому адресу.
Какой ключ работает на какой поверхности
Ключи не взаимозаменяемы, и это проверяется, а не подразумевается.
| Ключ | Поверхность | Что им можно |
|---|---|---|
| Токен доступа пользователя | основной API | всё, что разрешает роль пользователя |
Браузерный токен pp_bt_… |
приём | запись событий, identify, записи сессий, чтение публичной конфигурации сбора, захват элемента |
Серверный ключ pp_sk_… |
приём | запись событий, identify, alias |
Устаревший ключ pp_wk_… |
приём | старый широкий профиль, только миграция |
Токен релизов pp_rel_… |
основной API | ровно одна операция: отметка деплоя из CI/CD |
Разбор каждого типа ключа приёма — на странице типов ключей. Как получить токен доступа и что делать с истёкшим — на странице аутентификации.
Чего делать нельзя
| Что сделали | Что придёт |
|---|---|
| Ключ приёма в основной API | 401 unauthorized |
| Токен доступа в приём | 401 unauthorized |
| Браузерный токен или серверный ключ в адресе запроса | 401 unauthorized |
Путь приёма /v1/… на хосте основного API |
404 not_found |
Путь /api/v1/… на хосте приёма |
404 not_found |
Первые два случая — самая частая ошибка. Основной API ждёт токен доступа
пользователя и не понимает ключей приёма; приём разбирает только значения с
префиксами pp_bt_, pp_sk_ и
pp_wk_ и не понимает токенов доступа. Оба ответят 401, и текст
ответа не подскажет, что дело именно в типе ключа: сообщения об ошибках
аутентификации намеренно не помогают подбирать значения.
Ещё одна асимметрия, которая удивляет: приём отвечает на кросс-доменные
предзапросы браузера разрешающим заголовком с *, но это разрешение
транспорта, а не авторизация. Браузерный токен по-прежнему обязан прийти с
домена из своего точного списка, иначе будет 403 credential_origin_forbidden.
Подробности — в настройке origin.
Служебная проверка
/healthz — единственный метод, который отвечает у обеих поверхностей,
не требует ключа и лежит в корне сервиса, а не под /api/v1.
# основной API: 200, если доступна база данных
curl -i https://YOUR_ACTIONPULSE_HOST/healthz
# приём событий: 200, если жива очередь событий
curl -i https://YOUR_ACTIONPULSE_INGEST_HOST/healthzУспех — 200 с телом {"status":"ok"}. Недоступная зависимость — 503
с обычным конвертом ошибки. Проверка отвечает на разные вопросы у разных
сервисов: у основного API — доступна ли база данных, у приёма — жива ли очередь,
в которую он публикует события. Поэтому проверять надо оба адреса: один
работающий сервис ничего не говорит о втором.
Задача → поверхность → раздел справочника
| Задача | Поверхность | Раздел |
|---|---|---|
| Отправить события, связать идентификаторы, отправить записи сессий | приём | /api/ingest/ |
| Войти, обновить или завершить сессию, принять приглашение | основной | /api/auth/ |
| Выпустить, ротировать, отозвать ключ приёма | основной | /api/api-keys/ |
| Создать проект, изменить или удалить его | основной | /api/projects/ |
| Участники, роли, приглашения, вход через внешний провайдер | основной | /api/org/ |
| Воронки, удержание, сегментация, пути, каталог событий | основной | /api/queries/ |
| SQL по своим событиям | основной | /api/sql-console/ |
| Сохранённые отчёты и панели | основной | /api/reports/, /api/dashboards/ |
| Сырые события списком и живой поток | основной | /api/events/ |
| Выгрузка результата отчёта и сырых событий | основной | /api/exports/ |
| Контракты событий и нарушения схемы | основной | /api/registry/ |
| Уведомления, отметки релизов, недельная сводка | основной | /api/alerts/ |
| Загрузка истории из CSV, Amplitude, ClickHouse | основной | /api/imports/ |
| Удаление данных субъекта и данных форм | основной | /api/privacy/ |
| Проверка живости сервиса | обе | /api/service/ |
Что проверить
- Адрес приёма и адрес основного API в конфигурации вашего приложения — это два
разных значения. Один хост, подставленный в оба места, даёт
404на половине запросов. - В браузерном коде нет ничего, кроме браузерного токена: поиск по префиксу
pp_sk_по всему фронтенду и по контейнеру тег-менеджера занимает минуту. /healthzотвечает200на обоих адресах. Если у приёма он отвечает503, отправка событий тоже не гарантирована: считайте такие запросы неудачными и повторяйте их, а не списывайте как доставленные.- Клиент проверяет
rejectedв ответе приёма и код ответа основного API, а не только факт «запрос ушёл». - Разбор симптомов по кодам ответа — в дереве диагностики.