/yandex-metrika

API-сегменты

API-сегмент — сохранённое выражение отбора данных в формате параметра filters API отчётов. Он подходит для подбора аудитории в Яндекс Директе.

Возможности и ограничения

• На одном счётчике можно создать до 500 API-сегментов.
• API-сегменты не отображаются в интерфейсе Метрики.
• Их можно использовать в Директе, но нельзя выбрать в Яндекс Аудиториях.
• Сегменты из интерфейса и API учитываются отдельно: всего до 1000 на счётчик.
• Имя содержит 1–255 символов, выражение — 1–65535 символов по схеме API.
• Для собственного сегмента в условии Директа должно накопиться не менее 100 пользователей.
• Новые данные попадают в сегмент в течение 180 минут, сам сегмент пересчитывается ежедневно.

Последние два условия важно проверять прежде, чем повторно менять доступы: сегмент может быть доступен кабинету, но ещё не готов к использованию. Подробнее: условия формирования сегментов аудитории и сегмент Метрики для ретаргетинга.

Относительный период

Период от 1 до 540 дней в Директе задаётся только для целей Метрики. Для сохранённого сегмента Метрики период в Директе выбрать нельзя. Если аудитория должна зависеть от давности визита, добавь условие по дате в само выражение сегмента.

Текущий API принимает относительную дату в выражении. Например, посетители предыдущего календарного дня без роботов:

ym:s:date=='yesterday' AND ym:s:isRobot=='No'

Другие скользящие периоды:

# Ровно два календарных дня назад
ym:s:date=='2daysAgo'

# За два завершённых календарных дня: позавчера и вчера
ym:s:date>='2daysAgo' AND ym:s:date<'today'

# За семь завершённых календарных дней до сегодняшнего
ym:s:date>='7daysAgo' AND ym:s:date<'today'

# От двух до семи календарных дней назад включительно
ym:s:date>='7daysAgo' AND ym:s:date<='2daysAgo'

При необходимости добавь к любому выражению AND ym:s:isRobot=='No'. Не используй диапазон от 7daysAgo до today включительно для семидневного периода: он охватывает восемь календарных дат.

Живая проверка показала, что yesterday работает в filters, а API-сегмент сохраняет это значение буквально. Поэтому ожидается, что дата вычисляется заново при ежедневном пересчёте сегмента. Однако официальная документация явно описывает относительные даты только для date1 и date2 и отдельно не гарантирует их повторное вычисление внутри сохранённого выражения. Перед производственным использованием проверь переход сегмента через границу суток. См. параметры периода отчёта и список группировок.

yesterday означает предыдущий календарный день в часовом поясе счётчика, а не последние 24 часа. Диапазон дат отчёта (date1 и date2) в сегмент не входит и на его аудиторию не влияет.

«Был визит» и «последний визит»

ym:s:date — дата отдельного визита. Условие по ней означает, что у посетителя был хотя бы один подходящий визит, но не определяет дату его последнего визита. Например, посетитель, который заходил пять дней назад и снова зашёл сегодня, соответствует диапазону от двух до семи дней назад по старому визиту.

Если нужны только посетители, чей последний визит был в заданном диапазоне, не используй обычное условие по ym:s:date как равнозначную замену. В публичной документации API нет стабильного относительного поля для даты последнего визита посетителя; такое условие требует отдельного подтверждённого решения.

Не заменяй это условие на ym:s:daysSincePreviousVisit==1: такая группировка означает, что между текущим и предпоследним визитами посетителя прошёл один день, а не то, что последний визит был вчера.

Выражение использует синтаксис filters: AND, OR, NOT, скобки и операторы множеств EXISTS, ALL, NONE. Ограничения конкретного отчёта тоже важны: до 20 отдельных условий, до 10 уникальных группировок и метрик и до 100 значений в одном условии. Строка filters проверочного отчёта ограничена 10 000 символами, хотя сохранённое выражение сегмента по схеме объекта может быть до 65 535 символов. Если фильтр использует метрику, добавь её в metrics проверочного отчёта.

Примеры:

ym:s:isRobot=='No'
ym:s:deviceCategory=='mobile' AND ym:s:isRobot=='No'
EXISTS(ym:pv:URL=@'/catalog/')
EXISTS(ym:s:paramsLevel1=='client_type' AND ym:s:paramsLevel2=='new')

Синтаксис и примеры: сегментация в API отчётов. Различия способов сохранения: сегментация данных.

Методы API

Создать сегмент может владелец, редактор или аналитик. Удалять — владелец или редактор. Для записи токену нужен доступ metrika:write.

Команды

# Список и подробности
bash scripts/segments.sh --counter 123456 --action list
bash scripts/segments.sh --counter 123456 --action get --segment-id 987

# Сначала показать план
bash scripts/segments.sh --counter 123456 --action create \
  --name "Мобильные без роботов" \
  --expression "ym:s:deviceCategory=='mobile' AND ym:s:isRobot=='No'"

# Выполнить тот же план
bash scripts/segments.sh --counter 123456 --action create \
  --name "Мобильные без роботов" \
  --expression "ym:s:deviceCategory=='mobile' AND ym:s:isRobot=='No'" \
  --apply

delete требует --segment-id. После записи сценарий повторно читает объект. Изменяющий запрос не повторяется автоматически: при обрыве связи сначала найди объект по уникальному имени. Повторное create с теми же названием и выражением и повторное delete уже отсутствующего ID завершаются без новой записи. Сценарий не изменяет и не удаляет сегменты, чей segment_source отличается от api. Перед удалением проверь кампании вручную: API Метрики не сообщает, где сегмент уже используется, а удаление может нарушить условия подбора аудитории.