/yandex-direct

Изменения в рекламном кабинете

Пользователь должен понимать, какой объект меняется и что получится после записи. Просьба «исправь август на сентябрь и цену на 1200 рублей» уже разрешает эту правку. Покажи конкретные значения до и после, выполни её и сообщи проверенный результат. Дополнительное «записать?» не требуется. Если месяц, новая цена, бюджет или набор объявлений не определены, сначала уточни недостающие значения.

Не путай цену в тексте объявления со ставкой за клик или бюджетом кампании. Это разные поля с разными последствиями.

Порядок работы

1. Выбери кабинет и найди кампанию. Прочитай её объявления, группы и нужные параметры. При совпадающих названиях используй идентификаторы.
2. Подготовь только запрошенные изменения. Сохрани остальные тексты, ссылки, изображения и параметры.
3. Покажи таблицу: объект, поле, было, станет. Для большой выборки приложи полный перечень, а в сообщении назови количество объектов и характер правок.
4. Запусти команду с --apply, если пользователь поручил выполнить изменения. Запрос «посмотри» или «предложи» разрешает только просмотр: используй режим без записи.
5. Сообщи, какие изменения подтверждены повторным чтением. Если часть не применилась или результат неизвестен, назови эти объекты отдельно. Для объявления добавь его фактический статус модерации, если он изменился.

Пример показа:

Это пример формата. Значения «было» всегда берутся из свежего ответа API.

Режимы команд

Создание кампании и изменение мест показа: PLACEMENTS.md. campaign_write.py strategy --placement … меняет выбранные места с сохранением текущего типа стратегии, бюджета и целей; для запрета РСЯ отдельно выключается сетевая часть. Перед запуском проверьте указанные в справочнике ограничения API.

Команды ниже запускаются из каталога скилла. Заменяй примерные логины и идентификаторы данными выбранного кабинета.

Без --apply или с --dry-run команда читает актуальные данные, проверяет ограничения API и выводит полный план. Рекламный кабинет не изменяется. Проверка использует API и расходует его баллы.

С --apply команда выводит план, сохраняет исходное состояние в журнал, отправляет запрос и перечитывает результат. Ввод через stdin, yes, FIFO и удержание одного процесса для подтверждения не нужны. При повторном запуске данные читаются заново.

--json отдаёт машиночитаемый результат в stdout, а пояснения — в stderr. Поле preview содержит полный план, written — проверенные изменения, accepted — элементы, принятые API. Успешный ответ API без успешного перечитывания не считается проверенной записью.

Месяц и цена в объявлении

Товарные объявления ShoppingAd получают товары, цены и изображения из фида. Управление источником, текстом по умолчанию и фильтрами описано в фидах и товарных объявлениях. Перед изменением определите, нужна ли правка данных каталога, настроек фида или самого объявления.

Команды ad update и ad set-title меняют комбинаторные ResponsiveAd. Старые TextAd пропускаются: назови их в остатке и предложи правку в интерфейсе. Для быстрых ссылок, промоэлементов и других отдельных объектов нужны собственные операции; замена текста объявления их не обновляет.

Замена одного заголовка с сохранением остальных частей объявления:

python3 scripts/ads_write.py ad set-title \
  --account example --ad 123456 1 'Акция в сентябре'

Та же правка с выполнением:

python3 scripts/ads_write.py ad set-title \
  --account example --ad 123456 1 'Акция в сентябре' --apply

Замена текстов:

python3 scripts/ads_write.py ad update \
  --account example --ad 123456 \
  --text 'Установка от 1200 рублей. Акция в сентябре.' \
  --text 'Гарантия на работы. Запишитесь на замер.' --apply

--text заменяет список текстов целиком. Перечисли каждый сохраняемый текст отдельным аргументом; один --text оставит только один текст. То же относится к повторяемым --title, --image и --video. Поля без аргументов сохраняются по свежему чтению. Для очистки поддерживаемого поля используется отдельный --clear.

Отбор --ad можно повторять; также доступны --group и --campaign. Прежде чем править весь отбор, проверь все найденные объявления. Не переноси цену или месяц на несвязанные предложения только из-за общей кампании.

Обновление объявления может потребовать повторной модерации. Смена текста на действующей кампании сама по себе не подтверждает, что новый текст уже показывается.

Быстрые ссылки и уточнения

Создание и изменение быстрых ссылок и уточнений, их привязка к новому или существующему объявлению: EXTENSIONS.md. Для них сначала показывай сами тексты и адреса, затем создавай нужные объекты и меняй привязки.

Загрузка изображений

Сначала проверь саму картинку: она должна соответствовать предложению, включая товар, надписи, цены и сроки. Для нового материала можно использовать файл пользователя или подготовить изображение по его задаче. Сохраняй исходный файл вне cache/: кеш может очищаться после записи в кабинет. Исходник нужен для повторного использования и сравнения вариантов.

Предпросмотр загружает картинку в HTML, а images.py upload — в библиотеку выбранного рекламного кабинета. Это разные действия. Для записи нужен локальный файл; если дан адрес, сначала скачай и проверь изображение. Один URL вместо AdImageHash в объявление передать нельзя.

Проверка файла и план без загрузки в кабинет:

python3 scripts/images.py upload --account example \
  --file /path/to/roof.png --name 'Кровля — новый вариант'

Загрузка того же файла:

python3 scripts/images.py upload --account example \
  --file /path/to/roof.png --name 'Кровля — новый вариант' --apply

Команда показывает формат, размеры, объём файла и локальную контрольную сумму SHA-256. Бинарное содержимое не выводится в план и не записывается целиком в журналы. После загрузки команда проверяет изображение через AdImages.get и показывает назначенный Директом AdImageHash, фактическое имя, тип и адрес. SHA-256 исходного файла и AdImageHash — разные идентификаторы.

Для обычных изображений объявления API принимает JPG, PNG и GIF до 10 МиБ. Размеры и пропорции проверяются по limits.json, раздел media.image. Квадратная картинка от 450×450 до 5000×5000 подходит по геометрии; для широких картинок действуют отдельные требования. WebP, поддерживаемый предпросмотром, для загрузки через этот API не подходит. Команда не обрезает и не перекодирует файл молча.

Полученный хеш передаётся существующей команде создания объявления:

python3 scripts/ads_write.py ad create --account example --group 12345 \
  --title 'Кровельные материалы' --text 'Выберите материалы для вашего дома.' \
  --href https://example.com/ --image HASH --apply

При обновлении ad update --image укажи весь итоговый список изображений, включая сохраняемые. После записи перечитай объявление и проверь новый хеш в ResponsiveAd.AdImages.Items[].ImageHash. Признак Associated у картинки означает использование хотя бы где-нибудь и не подтверждает привязку к нужному объявлению. Для показа результата используй preview.py matrix --ad ID.

Идентичные изображения Директ объединяет: повторная загрузка может вернуть уже существующий хеш. Не обещай переименование ранее загруженного файла; покажи фактически возвращённое имя. При неизвестном исходе не повторяй загрузку автоматически: сначала проверь, что появилось в кабинете.

Если хеш получен, его можно перечитать отдельно:

python3 scripts/images.py get --account example --hash HASH

API не возвращает исходное поле ImageData: сообщение об этом не означает ошибку загрузки. Подтверждение команды относится к существованию картинки по возвращённому хешу; для проверки содержания открой её OriginalUrl.

Загрузка картинки и создание объявления не означают прохождения модерации или запуска показов. Для проверки загрузки достаточно черновика объявления; если пользователь поручил запуск, отдельно проверь готовность кампании и модерацию.

Описание API: загрузка, чтение, требования к изображениям.

Название и сроки кампании

Название:

python3 scripts/campaign_write.py name \
  --account example --campaign 12345 'Установка — сентябрь 2026' --apply

Период проведения:

python3 scripts/campaign_write.py dates \
  --account example --campaign 12345 \
  --start 2026-09-01 --end 2026-09-30 --apply

Название месяца в объявлении и дата завершения кампании не связаны автоматически. Меняй даты только тогда, когда пользователь попросил изменить период показов. Передача --clear-end снимает дату окончания.

Другие изменения

Добавление целей с сохранением прежних, переход с одной цели на несколько и различие цены и ценности конверсии: GOALS.md.

Все команды поддерживают справку --help:

• campaign_write.py: создание, название, даты, стратегия и бюджеты, цели, счётчики, параметры URL, мониторинг, расписание, минус-фразы, исключённые площадки и IP, состояние кампании.
• account_budget.py: просмотр, установка и снятие недельного бюджета всего кабинета.
• ads_write.py: объявления, группы, перенос дополнительного заголовка, условия показа и состояние объектов.
• keywords_write.py: ключевые и минус-фразы, наборы минус-фраз, замена и приостановка фраз.
• bids.py: ставки и корректировки.
• cross_negative.py: взаимная минусация групп.

Для создания кампании и изменения бюджета сначала читай BUDGETS.md: общий лимит кабинета, сумма для проверки трафика, бюджет кампании или пакета. Для изменения стратегии, цели оптимизации или бюджета нужны конкретные значения пользователя. Рекомендация увеличить ставки по исторически результативным запросам сама по себе не разрешает их изменение.

При создании кампании команда показывает автоматически добавленные параметры. Явно переданные параметры имеют приоритет. --remember у команд кампаний и объявлений сохраняет выбранные схемы имени и UTM для следующих задач этого кабинета; без него новый выбор действует только в текущей задаче.

Проверка результата и журнал

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

Исходное состояние и результат лежат в journal/<кабинет>/audit-log.jsonl. В записи есть before, requested, after, идентификатор запроса и найденные расхождения. Журнал содержит данные кабинета и не публикуется в репозитории.

unknown означает, что результат не удалось установить, а despite — что изменение обнаружено после ошибки запроса. При этих результатах не повторяй создание автоматически: сначала найди объект и проверь, что уже применилось. При частичном выполнении продолжай только с проверенным остатком задачи.