Быстрые ссылки и уточнения
Быстрая ссылка состоит из заголовка, адреса и необязательного описания.
Директ хранит их набором: у объявления указан SitelinkSetId, а содержимое
возвращает Sitelinks.get. Уточнение — отдельный объект AdExtension типа
CALLOUT; объявление хранит список его ID. Самостоятельного объекта
«набор уточнений» в API нет: набором служат привязки конкретного объявления.
Один набор ссылок или одно уточнение могут использоваться в нескольких объявлениях. Для изменения содержимого создай новый объект и замени привязку только у выбранных объявлений. Остальные привязки сохрани. Старые объекты автоматически не удаляй: они могут ещё использоваться.
Прочитать содержимое
Одна карточка объявления сразу включает быстрые ссылки и уточнения:
uv run scripts/ads.py --account client-shop --ad 123 --jsonДля аудита нескольких объявлений или кампании добавь --with-extensions:
uv run scripts/ads.py --account client-shop --campaign 456 --with-extensions --jsonЧтобы найти дополнения у ShoppingAd и ListingAd, читай объявления по ID,
группам или кампаниям и сопоставляй привязки в ответе. Фильтры Ads.get
SelectionCriteria.SitelinkSetIds и AdExtensionIds эти типы не охватывают.
Содержимое находится в коллекциях SitelinksSets и AdExtensions; их ID
сопоставляются со связями в исходных объявлениях. Полная выгрузка сохранена
по указанному командой пути, даже если сводка сокращена. Её можно передать
в preview.py matrix --from-json ФАЙЛ --ad ID без ручной перепечатки.
Если известны только ID наборов или уточнений, прочитай их напрямую:
uv run scripts/extensions.py --account client-shop sitelinks get --id 100 --id 101
uv run scripts/extensions.py --account client-shop callouts get --id 200 --id 201ExtensionsRead сообщает полноту чтения, отсутствующие ID и ошибки. Ошибка
чтения не означает, что дополнения нет. Для свежего чтения добавь --no-cache;
перед записью команды всегда читают заново. Получение адреса через API само по
себе не проверяет доступность страницы: при аудите ссылок отдельно открой каждый
адрес, проверь переходы и соответствие предложения странице.
Создать содержимое
Для быстрых ссылок подготовь JSON со всем итоговым набором. При правке удобно
взять массив Sitelinks из прочитанного набора и изменить нужные поля:
[
{"Title": "Каталог", "Href": "https://example.com/catalog", "Description": "Выберите подходящую модель"},
{"Title": "Доставка", "Href": "https://example.com/delivery"}
]Сохрани его, например, в sitelinks.json, вне каталога кеша. Покажи пользователю
заголовки, адреса и описания до и после. Не теряй метки URL и неизменяемые ссылки.
uv run scripts/extensions.py --account client-shop sitelinks create --file sitelinks.json
uv run scripts/extensions.py --account client-shop sitelinks create --file sitelinks.json --apply
uv run scripts/extensions.py --account client-shop callouts create --text "Доставка по России" --text "Гарантия 2 года" --applyБез --apply показывается план; с ним команда создаёт объекты и проверяет их
повторным чтением. Используй фактически полученные ID для следующего шага.
Создание в библиотеке ещё не добавляет дополнение в объявление.
Для уточнений команда сначала читает действующие уточнения кабинета. Если текст
уже есть, возвращает его ID; создаёт только недостающие тексты. Сравнение точное,
без изменения регистра и пробелов. В JSON существующие ID и тексты находятся в
reused_callouts, принятые новые ID — в accepted, подтверждённые чтением —
в written. Если все тексты найдены, запись не выполняется. Ошибка чтения
останавливает создание: неполную библиотеку нельзя считать отсутствием уточнений.
В наборе допускается до 8 ссылок. Заголовок — до 30 символов, описание — до 60, адрес — до 1024; уточнение — до 25 символов. Команды используют общий справочник ограничений. Итоговую допустимость сочетания и модерацию определяет Директ.
Привязать, заменить или снять
Команда bind работает с ResponsiveAd, TextAd, товарными ShoppingAd
и объявлениями каталога ListingAd. Укажи один ID объявления
или повтори --ad для нескольких. Новый ID набора заменяет текущий набор целиком;
каждый --callout-id входит в полный итоговый список уточнений. Чтобы изменить
одно уточнение, сохрани в списке ID остальных. Поле, которое не названо, не меняется.
uv run scripts/extensions.py --account client-shop bind --ad 123 --sitelink-set 102 --callout-id 200 --callout-id 202
uv run scripts/extensions.py --account client-shop bind --ad 123 --sitelink-set 102 --callout-id 200 --callout-id 202 --applyПлан содержит содержимое дополнений «было → станет». После записи проверяется
итоговая привязка в самом объявлении. У ResponsiveAd API также требует
заголовки и тексты: команда сохраняет прочитанные значения. Если после подготовки
плана изменились привязки, тип или состояние объявления, а у ResponsiveAd —
ещё и сохраняемые заголовки или тексты, команда останавливается для нового чтения.
У ShoppingAd и ListingAd команда меняет только дополнения: фид, фильтры,
источники заголовков и текст по умолчанию не передаются и сохраняются в Директе.
Отдельный Href для привязки их быстрых ссылок не требуется.
Перед привязкой команда проверяет выбранные уточнения среди действующих
(States: ["ON"]); удалённые ID не попадут в план записи.
Для снятия привязки используй явную очистку:
uv run scripts/extensions.py --account client-shop bind --ad 123 --clear-sitelinks --apply
uv run scripts/extensions.py --account client-shop bind --ad 123 --clear-callouts --applyДля нового объявления порядок тот же: создай комбинаторное объявление через
ads_write.py ad create или товарное через shopping.py add
(фиды и товарные объявления), затем привяжи дополнения
к возвращённому ID через extensions.py bind. Если пользователь поручил создание или конкретную правку,
повторное разрешение на каждый технический шаг не требуется.
Сохранённые дополнения не обязательно показываются в каждом месте показа, включая товарную галерею. Проверяй нужный формат в предпросмотре Директа; наличие привязки в API подтверждает настройку, а не её показ в каждой карточке.
Изменение объявления может потребовать повторной модерации. Успех записи не
означает допуска к показам; сверяй статус через ads.py. При ошибке или
неизвестном исходе не повторяй создание вслепую: сначала проверь уже полученные
ID и выполненные привязки. Для показа пользователю используй
предпросмотр до и после.
Удалить из библиотеки
Удаление объекта из кабинета — отдельное действие по запросу пользователя:
uv run scripts/extensions.py --account client-shop sitelinks delete --id 100 --apply
uv run scripts/extensions.py --account client-shop callouts delete --id 201 --applyAPI разрешает удаление только после снятия всех привязок. Команда их сама не
снимает. Удалённое уточнение может ещё возвращаться по ID с State: DELETED;
это не действующее уточнение и не ошибка удаления.
Команда проверяет наличие среди действующих уточнений; повторное удаление
уже удалённого уточнения не отправляется в API.
Контракты API: быстрые ссылки, уточнения, изменение объявления.