эксплуатационные шаблоны команд

Эксплуатационные шаблоны - это стабильные cURL-команды, которыми регулярно проверяют жизнеспособность интеграции.

Простыми словами: это "дежурный набор команд", который быстро показывает состояние API-взаимодействия.

Минимальный набор проверок:

1. Smoke auth-check

• Проверить валидность токена и доступ к базовому endpoint.
• Endpoint: GET /management/v1/counters
• Пример команды:

curl -sS -H "Authorization: OAuth <token>" -H "Accept: application/json" "https://api-metrika.yandex.net/management/v1/counters"

• Критерий прохождения:
• HTTP 2xx и валидная структура списка счетчиков.

1. Smoke read-check

• Проверить чтение базового отчета.
• Endpoint: GET /stat/v1/data
• Пример команды:

curl -sS -H "Authorization: OAuth <token>" -H "Accept: application/json" "https://api-metrika.yandex.net/stat/v1/data?ids=<counter_id>&metrics=ym:s:visits&date1=today-7&date2=today"

• Критерий прохождения:
• HTTP 2xx, поле данных присутствует, метрика ym:s:visits возвращает значения.

1. Регресс-проверка ключевых метрик

• Выполнить набор эталонных запросов по важным KPI.
• Сравнить структуру ответа и допустимые диапазоны значений.
• Пример набора команд:
• визиты:

curl -sS -H "Authorization: OAuth <token>" "https://api-metrika.yandex.net/stat/v1/data?ids=<counter_id>&metrics=ym:s:visits&date1=today-7&date2=today"

• отказы:

curl -sS -H "Authorization: OAuth <token>" "https://api-metrika.yandex.net/stat/v1/data?ids=<counter_id>&metrics=ym:s:bounceRate&date1=today-7&date2=today"

• глубина просмотра:

curl -sS -H "Authorization: OAuth <token>" "https://api-metrika.yandex.net/stat/v1/data?ids=<counter_id>&metrics=ym:s:pageDepth&date1=today-7&date2=today"

• Критерий прохождения:
• ответы всех эталонных запросов успешны (2xx);
• структура JSON не изменилась относительно ожидаемой;
• значения метрик в допустимых диапазонах для выбранного периода.

1. Диагностический шаблон

• Команда с -i, -v, таймаутами и контролируемым retry для быстрого разбора сбоев.
• Пример команды:

curl -v -i --connect-timeout 5 -m 25 --retry 2 --retry-delay 1 -H "Authorization: OAuth <token>" "https://api-metrika.yandex.net/stat/v1/data?ids=<counter_id>&metrics=ym:s:visits&date1=today-7&date2=today"

• Критерий прохождения:
• при нормальной работе запрос завершается без таймаута;
• при сбое в логе есть достаточно данных для классификации причины (доступ, лимиты, параметры, временная недоступность).

Рекомендуемые плейсхолдеры для шаблонов:

• <token> - OAuth-токен с минимально необходимыми правами;
• <counter_id> - тестовый счетчик, доступный для интеграции;
• date1/date2 - фиксированный период для сравнимости регресс-проверок.

Организация эксплуатационного набора:

• фиксировать шаблоны в документации и хранить их как версионируемый артефакт;
• отделять шаблоны для dev/stage/prod;
• запускать smoke после релизов и инфраструктурных изменений;
• использовать те же шаблоны при инцидентах для ускорения triage.

Практический вывод:

• Повторяемые команды превращают разрозненные проверки в управляемый процесс.
• Для Метрики это снижает время обнаружения деградации и повышает предсказуемость аналитических выгрузок.