--- metadata: - name: generator content: Diplodoc Platform v5.50.2 alternate: - https://yandex.com/dev/direct/doc/dg-v4/en/live/CreateOrUpdateBanners.md - https://yandex.com/dev/direct/doc/dg-v4/ru/live/CreateOrUpdateBanners.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/direct/doc/dg-v4/ru/llms.txt # CreateOrUpdateBanners (Live) Создает или изменяет группы объявлений, объявления и фразы. Если кампания активна, добавленные и измененные объявления автоматически отправляются на модерацию. Для кампаний в статусе “Черновик” отправить объявление на модерацию можно с помощью метода [ModerateBanners](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/ModerateBanners.md). ## Ограничения {% note alert %} Метод поддерживает только текстово-графические объявления. Для работы с объявлениями всех типов используйте сервис [Ads](https://yandex.ru/dev/direct/doc/ru/ads/ads) API версии 5. [Подробнее о типах объявлений...](https://yandex.ru/dev/direct/doc/dg/objects/ad.md) {% endnote %} В одном вызове метода можно передать не более 1000 объявлений. Для одной кампании можно вызвать метод не более 1000 раз в сутки. При вызове метода расходуются баллы. Если баллов недостаточно, возвращается сообщение об ошибке [152](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/ErrorCodes.md#ErrorCode152). Чтобы обновить только цены за клик, рекомендуется использовать метод [UpdatePrices (Live)](https://yandex.com/dev/direct/doc/dg-v4/ru/live/UpdatePrices.md), при вызове которого баллы не расходуются. Кампания может содержать не более 1000 групп объявлений. Количество объявлений в группе — не более 50. Количество ключевых фраз в группе — не более 200. ## Новое в версии Live 4 Добавлен входной параметр AutoMinusWords. Добавлен входной параметр AgeLabel. Добавлен входной параметр Currency. Добавлены входные параметры AdGroupID и AdGroupName. Добавлен входной параметр AdGroupMobileBidAdjustment. Добавлен входной параметр Type. ## Входные данные {#input} Ниже показана структура входных данных в формате JSON. ```javascript { "method": "CreateOrUpdateBanners", "param": [ { /* BannerInfo */ "BannerID": (long), "CampaignID": (int), "AdGroupID": (long), "AdGroupName": (string), "Type": (string), "Title": (string), "Text": (string), "Href": (string), "Geo": (string), "ContactInfo": { /* ContactInfo */ "ContactPerson": (string), "Country": (string), "CountryCode": (string), "City": (string), "Street": (string), "House": (string), "Build": (string), "Apart": (string), "CityCode": (string), "Phone": (string), "PhoneExt": (string), "CompanyName": (string), "IMClient": (string), "IMLogin": (string), "ExtraMessage": (string), "ContactEmail": (string), "WorkTime": (string), "OGRN": (string), "PointOnMap": { /* MapPoint */ "x": (float), "y": (float), "x1": (float), "y1": (float), "x2": (float), "y2": (float) } }, "Phrases": [ { /* BannerPhraseInfo */ "PhraseID": (long), "Phrase": (string), "IsRubric": (string), "Price": (float), "ContextPrice": (float), "AutoBroker": (string), "AutoBudgetPriority": (string), "UserParams": { /* PhraseUserParams */ "Param1": (string), "Param2": (string) }, "Currency": (string) } ... ], "Sitelinks": [ { /* Sitelink */ "Title": (string), "Href": (string) } ... ], "MinusKeywords": [ (string) ... ], "AutoMinusWords": (string), "AgeLabel": (string), "AdGroupMobileBidAdjustment": (int) } ... ] } ``` Ниже приведено описание параметров. #| || **Параметр** | **Описание** | **Требуется** || || **Объект BannerInfo** || || `BannerID` | Идентификатор объявления. Для создания объявления задают 0, для изменения параметров объявления указывают его идентификатор. | Да || || `CampaignID` | Идентификатор кампании. | Да || || `AdGroupID` | Идентификатор группы объявлений. Для создания группы объявлений параметр не указывают или задают значение 0. Для добавления объявления в существующую группу необходимо указать идентификатор этой группы. Для изменения параметров объявления или группы параметр указывать необязательно. | Нет || || `AdGroupName` | Название группы объявлений (до 255 символов). Если не указано, то группе автоматически присваивается название вида “AdGroup №”. Если длина строки превышает 255 символов, лишние символы будут отброшены. | Нет || || `Type` | Тип объявления: Desktop или Mobile. Параметр указывается только при создании объявления. Если значение не задано, подразумевается Desktop. При попытке изменить значение параметра для существующего объявления возвращается ошибка с кодом [71](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/ErrorCodes.md#ErrorCode71). | Нет || || `Title` | Заголовок объявления (до 33 символов, включая пробелы и знаки препинания). | Да || || `Text` | Текст объявления (до 75 символов, включая пробелы и знаки препинания). | Да || || `Href` | Ссылка на сайт рекламодателя. Может содержать подстановочные переменные. | Один из параметров — `Href` или `ContactInfo` || || `ContactInfo` | Объект `ContactInfo` с контактными данными рекламодателя (визитка). || || `Geo` | Идентификаторы регионов, для которых показы включены или выключены. Идентификатор 0 или пустая строка — показывать во всех регионах. Чтобы выключить показ в регионе, перед идентификатором региона ставят минус, например “1,-219” — показывать для Москвы и Московской области, кроме Черноголовки. Регионы с минусом нельзя использовать, если указан нулевой регион. Также параметр не должен состоять только из минус-регионов. Полный список регионов можно получить с помощью метода [GetRegions](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetRegions.md). Указывать параметр необязательно, если значение `AdGroupID` отлично от 0 и не задан ни один из параметров `AdGroupName`, `Phrases`, `MinusKeywords`, `AutоMinusWords`. | Нет || || `Phrases` | Массив объектов `BannerPhraseInfo`, содержащих информацию о фразах. Для группы объявлений должна быть задана хотя бы одна фраза или условие ретаргетинга. Количество фраз в группе — не более 200. Указывать фразы необязательно в случае, если значение `AdGroupID` отлично от 0 и при этом не задан ни один из параметров `Geo`, `MinusKeywords`, `AutоMinusWords`, а также в случае, если для группы задано хотя бы одно [условие ретаргетинга](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/retargeting.md). | Нет || || `Sitelinks` | Массив объектов `Sitelink` с [быстрыми ссылками](https://yandex.ru/support/direct/features/quick-links.xml)[быстрыми ссылками](https://yandex.com/support/direct/features/quick-links.xml). Массив должен содержать от 1 до 4 объектов `Sitelink` или отсутствовать. | Нет || || `MinusKeywords` | Массив минус-фраз, общих для всех ключевых фраз группы объявлений. Минус-фразу следует указывать без минуса перед первым словом. Не более 7 слов в минус-фразе. Длина каждого слова — не более 35 символов. Суммарная длина минус-фраз в массиве — не более 4096 символов. Оператор “!” или “+” перед словом не учитывается в суммарной длине. {% note info %} Минус-фразы, общие для всех групп в кампании, предпочтительно задавать в одноименном параметре кампании. {% endnote %} | Нет || || `AutoMinusWords` | Автоматически сделать фразы в группе объявлений непересекающимися — Yes/No. Предустановленное значение — No. | Нет || || `AgeLabel` | Возрастная категория. Для объявлений, относящихся к группе baby_food (соответствующее значение возвращается в массиве `AdWarnings`), — возраст ребенка в месяцах: '0months', '1months', '2months', ..., '12months'. Для прочих объявлений — возраст, на которую ориентирована информационная продукция. Возможные значения: '0+', '6+', '12+', '16+', '18+'. Если у объявления отсутствует возрастная категория, параметр не возвращается в ответах и игнорируется при попытке задать его. {% note alert %} Через API можно изменить только значение возрастной категории, если она есть у объявления. Чтобы изменить наличие/отсутствие возрастной категории, пожалуйста, обратитесь в [службу поддержки Директа](https://yandex.ru/support/direct/troubleshooting/moderation_dissent.xml)[службу поддержки Директа](https://yandex.com/support/direct/troubleshooting/moderation_dissent.xml). {% endnote %} | Нет || || `AdGroupMobileBidAdjustment` | Коэффициент настройки цен на мобильных устройствах. Используется для групп объявлений и указывается в процентах от ставки на десктопе. Диапазон значений от 50 до 1300. Подробнее о коэффициенте можно узнать в разделе[Корректировки ставок](https://yandex.ru/support/direct/impressions/bids-adjustment.xml)[Bid adjustments](https://yandex.com/support/direct/impressions/bids-adjustment.xml) помощи Директа. {% note info %} Если коэффициент для группы не указан, то в расчетах для установки ставки цен на мобильных устройствах используется коэффициент для кампании (параметр MobileBidAdjustment) при его наличии. {% endnote %} | Нет || || **Объект ContactInfo** || || `CompanyName` | Название организации. Не более 255 символов. | Да || || `ContactPerson` | Контактное лицо. Не более 155 символов. | Нет || || `Country` | Страна. Не более 50 символов. | Да || || `CountryCode` | Телефонный код страны. Значение должно начинаться со знака “+”, например “+7” для России. Исключение: если в поле `CityCode` указано значение “800”, то в поле `CountryCode` допустимо значение “8”. | Да || || `City` | Город. Не более 50 символов. | Да || || `Street` | Улица. Не более 55 символов. | Нет || || `House` | Номер дома. Не более 30 символов. | Нет || || `Build` | Номер строения или корпуса. Не более 10 символов. | Нет || || `Apart` | Номер квартиры или офиса. Не более 255 символов. | Нет || || `CityCode` | Телефонный код города. | Да || || `Phone` | Телефонный номер для связи. | Да || || `PhoneExt` | Добавочный телефонный номер для соединения через офисную АТС. | Нет || || `IMClient` | Тип сети мгновенного обмена сообщениями — icq, jabber, skype, mail_agent. | Нет || || `IMLogin` | Логин в сети мгновенного обмена сообщениями. | Нет || || `ExtraMessage` | Дополнительная информация о рекламируемом товаре или услуге. Не более 200 символов. | Нет || || `ContactEmail` | Адрес электронной почты. Не более 255 символов. | Нет || || `WorkTime` | Режим работы организации или режим обслуживания клиентов. Задается как строка, в которой указан диапазон дней недели, рабочих часов и минут. Дни недели обозначаются цифрами от 0 до 6, где 0 — понедельник, 6 — воскресенье. Минуты задают кратно 15: 0, 15, 30 или 45. Формат строки: `"день_с;день_по;час_с;минуты_с;час_до;мин_до"` Например, строка `"0;4;10;0;18;0"` задает такой режим: `0;4` — с понедельника по пятницу; `10;0` — с 10 часов 0 минут; `18;0` — до 18 часов 0 минут. Режим может состоять из нескольких строк указанного формата, например: "`0;4;10;0;18;0;5;6;11;0;16;0`". Здесь в дополнение к предыдущему примеру задан режим: `5;6` — с субботы по воскресенье; `11;0` — с 11 часов 0 минут; `16;0` — до 16 часов 0 минут. Круглосуточный режим работы задается строкой `"0;6;00;00;00;00"`. | Да || || `OGRN` | Код ОГРН для юридических лиц. | Нет || || `PointOnMap` | Объект `MapPoint`, задающий координаты местоположения клиента. По этим координатам ставится метка на карте. Если не заданы, метка ставится по указанному адресу клиента. | Нет || || **Объект MapPoint** || || `x` | Долгота точки. От -180 до 180. | Да || || `y` | Широта точки. От -90 до 90. | Да || || `x1` | Долгота левого нижнего угла области на карте. От -180 до 180. | Да || || `y1` | Широта левого нижнего угла области на карте. От -90 до 90. | Да || || `x2` | Долгота правого верхнего угла области на карте. От -180 до 180. | Да || || `y2` | Широта правого верхнего угла области на карте. От -90 до 90. | Да || || **Объект BannerPhraseInfo** || || `PhraseID` | Идентификатор фразы. Для добавления фразы задают 0, для изменения параметров фразы указывают ее идентификатор. | Нет || || `Phrase` | Ключевая фраза. Может содержать минус-слова, которые указывают со знаком минус перед словом, например [молния -гром -дождь]. Общие для нескольких фраз минус-слова предпочтительно задавать в параметре группы объявлений `MinusKeywords`. Длина ключевой фразы — не более 4096 символов. Оператор “!” перед минус-словом не учитывается в длине фразы (последовательность “-!” считается как один символ). Не более 7 слов во фразе, без учета стоп-слов и минус-слов. Каждое слово и минус-слово — не более 35 символов, без учета минуса перед минус-словом. | Да || || `IsRubric` | Признак того, что фраза является рубрикой Яндекс Каталога — Yes/No. Предустановленное значение — No. При значении Yes переданная фраза игнорируется. | Нет || || `Price` | Ставка на поиске Яндекса (в валюте, указанной в параметре `Currency`). Используется, только если для кампании выбрана стратегия с ручным управлением ставками. Максимальное и минимальное значения представлены в таблице. Если значение перед сохранением конвертируется из у. е. в валюту кампании, то оно округляется вверх с точностью до [шага торгов](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/multicurrency_const.md#increment) в этой валюте. Если после конвертации в валюту кампании значение оказалось меньше минимальной или больше максимальной ставки в этой валюте, оно устанавливается равным минимальной или, соответственно, максимальной ставке. | Для ручных стратегий || || `ContextPrice` | Ставка в Рекламной сети Яндекса (в валюте, указанной в параметре `Currency`). Параметр доступен для изменения в следующих случаях: 1. Для Рекламной сети выбрана стратегия MaximumCoverage. 1. Для Рекламной сети выбрана стратегия Default и фраза отключена на поиске за низкий CTR. Для новых фраз данное условие не актуально, поскольку фразы больше не отключаются за низкий CTR. Максимальное и минимальное значения представлены в таблице. Если значение перед сохранением конвертируется из у. е. в валюту кампании, то оно округляется вверх с точностью до [шага торгов](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/multicurrency_const.md#increment) в этой валюте. Если после конвертации в валюту кампании значение оказалось меньше минимальной или больше максимальной ставки в этой валюте, оно устанавливается равным минимальной или, соответственно, максимальной ставке. | Для стратегии MaximumCoverage || || `AutoBroker` | Включить/выключить автоброкер. Параметр не используется, переданное значение игнорируется. | Нет || || `AutoBudgetPriority` | Приоритет фразы при использовании автоматических стратегий. Возможные значения: - Low — низкий приоритет; - Medium — средний приоритет; - High — высокий приоритет. | Для стратегии WeeklyBudget || || `UserParams` | Объект `PhraseUserParams`. Содержит значения подстановочных переменных для формирования ссылки на сайт. | Нет || || `Currency` | Валюта, в которой указаны ставки. Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. Значение должно совпадать с валютой кампании. Если параметр отсутствует или равен NULL, подразумеваются условные единицы (у. е.). В этом случае, если кампания ведется в реальной валюте, переданные приложением ставки перед сохранением конвертируются в реальную валюту. Если значение отлично от NULL и не совпадает с валютой кампании (одной из кампаний), возвращается ошибка с кодом [245](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/ErrorCodes.md#BadCurrency). | Нет || || **Объект PhraseUserParams** || || `Param1` | Значение подстановочной переменной `{param1}`. Не более 255 байт. | При использовании подстановочных переменных в `Href` || || `Param2` | Значение подстановочной переменной `{param2}`. Не более 255 байт. || || **Объект Sitelink** || || `Title` | Текст быстрой ссылки (не более 30 символов). Суммарная длина текстов всех быстрых ссылок — не более 66 символов. | Да || || `Href` | Адрес быстрой ссылки. Может содержать подстановочные переменные. | Да || |# ## Результирующие данные {#output} При успешном выполнении метод возвращает массив, содержащий идентификаторы созданных/обновленных баннеров, как показано в следующем примере. ```javascript { "data": [33823946,33823947] } ``` ## Примеры входных данных {#example} ## Python ```python [ # Редактирование параметров объявления и группы { 'BannerID': 2571700, 'CampaignID': 1327837, 'AdGroupName': u'Название группы 1', 'Title': u'Заголовок объявления 1', 'Text': u'Текст объявления 1', 'Href': 'http://www.site.ru/page{param1}?ad={param2}', 'Geo': '2,183,3', 'ContactInfo': { 'ContactPerson': u'Александр Громов', 'Country': u'Россия', 'CountryCode': '+7', 'City': 'Moscow', 'Street': 'Leo Tolstoy', 'House': '16', 'Build': '', 'Apart': '', 'CityCode': '495', 'Phone': '739-70-00', 'PhoneExt': '', 'CompanyName': 'MyCompany', 'IMClient': 'jabber', 'IMLogin': 'email@ya.ru', 'ExtraMessage': u'все товары сертифицированы', 'ContactEmail': 'direct@yandex.ru', 'WorkTime': '0;4;10;00;18;00;5;6;13;00;16;00', 'OGRN': '1077746365113', 'PointOnMap': { 'x': 37.587942, 'y': 55.733783, 'x1': 37.573500, 'y1': 55.729389, 'x2': 37.600772, 'y2': 55.740249 } }, 'Phrases': [ { 'PhraseID': 37512102, 'Phrase': 'refrigerator', 'ContextPrice': 1.6, 'Price': 2.1, 'AutoBudgetPriority': 'Medium', 'UserParams': { 'Param1': '17', 'Param2': '177' } } ], 'Sitelinks': [ { 'Title': u'Доп. ссылка 1', 'Href': 'http://www.site.ru/?q=qu&action=1' }, { 'Title': u'Доп. ссылка 2', 'Href': 'http://www.site.ru/?q=qu&action=2' }, { 'Title': u'Доп. ссылка 3', 'Href': 'http://www.site.ru/?q=qu&action=3' } ], 'MinusKeywords': ['ice','cream'], 'AutoMinusWords': 'Yes' }, # Редактирование параметров объявления без редактирования параметров группы { 'BannerID': 2571707, 'CampaignID': 1327837, 'AdGroupID': 7542138, 'Title': 'Заголовок объявления 2', 'Text': 'Текст объявления 2', 'Href': 'http://www.site.ru/page{param1}?utm_content={phrase_id}' }, # Добавление объявления в группу { 'BannerID': 0, 'CampaignID': 1327837, 'AdGroupID': 4571251, 'Title': 'Заголовок объявления 3', 'Text': 'Текст объявления 3', 'Href': 'http://www.site.ru/page{param2}?utm_content={phrase_id}' } ] ``` ## PHP ```php array( # Редактирование параметров объявления и группы array( 'BannerID' => 2571700, 'CampaignID' => 1327837, 'Title' => 'Заголовок объявления 1', 'Text' => 'Текст объявления 1', 'Href' => 'http://www.site.ru/page{param1}?ad={param2}', 'Geo' => '2,183,3', 'ContactInfo' => array( 'ContactPerson' => 'Александр Громов', 'Country' => 'Россия', 'CountryCode' => '+7', 'City' => 'Moscow', 'Street' => 'Leo Tolstoy', 'House' => '16', 'Build' => '', 'Apart' => '', 'CityCode' => '495', 'Phone' => '739-70-00', 'PhoneExt' => '', 'CompanyName' => 'MyCompany', 'IMClient' => 'jabber', 'IMLogin' => 'email@ya.ru', 'ExtraMessage' => 'все товары сертифицированы', 'ContactEmail' => 'direct@yandex.ru', 'WorkTime' => '0;4;10;00;18;00;5;6;13;00;16;00', 'OGRN' => '1077746365113', 'PointOnMap' => array( 'x' => 37.587942, 'y' => 55.733783, 'x1' => 37.573500, 'y1' => 55.729389, 'x2' => 37.600772, 'y2' =55.740249 ) ), 'Phrases' => array( array( 'PhraseID' => 37512102, 'Phrase' => 'refrigerator', 'ContextPrice' => 1.6, 'Price' => 2.1, 'AutoBudgetPriority' => 'Medium', 'UserParams' => array( 'Param1' => '17', 'Param2' ='177' ) ) ), 'Sitelinks' => array( array( 'Title' => 'Доп. ссылка 1', 'Href' ='http://www.site.ru/?q=qu&action=1' ), array( 'Title' => 'Доп. ссылка 2', 'Href' ='http://www.site.ru/?q=qu&action=2' ), array( 'Title' => 'Доп. ссылка 3', 'Href' ='http://www.site.ru/?q=qu&action=3' ) ), 'MinusKeywords' => array('ice','cream'), 'AutoMinusWords' ='Yes' ), # Редактирование параметров объявления без редактирования параметров группы array( 'BannerID' => 2571707, 'CampaignID' => 1327837, 'AdGroupID' => 7542138, 'Title' => 'Заголовок объявления 2', 'Text' => 'Текст объявления 2', 'Href' ='http://www.site.ru/page{param1}?utm_content={phrase_id}' ), # Добавление объявления в группу array( 'BannerID' => 0, 'CampaignID' => 1327837, 'AdGroupID' => 4571251, 'Title' => 'Заголовок объявления 3', 'Text' => 'Текст объявления 3', 'Href' ='http://www.site.ru/page{param2}?utm_content={phrase_id}' ) ) ``` ## Perl ```perl [ # Редактирование параметров объявления и группы { 'BannerID' => 2571700, 'CampaignID' => 1327837, 'Title' => 'Заголовок объявления 1', 'Text' => 'Текст объявления 1', 'Href' => 'http://www.site.ru/page{param1}?ad={param2}', 'Geo' => '2,183,3', 'ContactInfo' ={ 'ContactPerson' => 'Александр Громов', 'Country' => 'Россия', 'CountryCode' => '+7', 'City' => 'Moscow', 'Street' => 'Leo Tolstoy', 'House' => '16', 'Build' => '', 'Apart' => '', 'CityCode' => '495', 'Phone' => '739-70-00', 'PhoneExt' => '', 'CompanyName' => 'MyCompany', 'IMClient' => 'jabber', 'IMLogin' => 'email@ya.ru', 'ExtraMessage' => 'все товары сертифицированы', 'ContactEmail' => 'direct@yandex.ru', 'WorkTime' => '0;4;10;00;18;00;5;6;13;00;16;00', 'OGRN' => '1077746365113', 'PointOnMap' ={ 'x' => 37.587942, 'y' => 55.733783, 'x1' => 37.573500, 'y1' => 55.729389, 'x2' => 37.600772, 'y2' =55.740249 } }, 'Phrases' => [ { 'PhraseID' => 37512102, 'Phrase' => 'refrigerator', 'ContextPrice' => 1.6, 'Price' => 2.1, 'AutoBudgetPriority' => 'Medium', 'UserParams' ={ 'Param1' => '17', 'Param2' ='177' } } ], 'Sitelinks' => [ { 'Title' => 'Доп. ссылка 1', 'Href' ='http://www.site.ru/?q=qu&action=1' }, { 'Title' => 'Доп. ссылка 2', 'Href' ='http://www.site.ru/?q=qu&action=2' }, { 'Title' => 'Доп. ссылка 3', 'Href' ='http://www.site.ru/?q=qu&action=3' } ], 'MinusKeywords' => ['ice','cream'], 'AutoMinusWords' ='Yes' }, # Редактирование параметров объявления без редактирования параметров группы { 'BannerID' => 2571707, 'CampaignID' => 1327837, 'AdGroupID' => 7542138, 'Title' => 'Заголовок объявления 2', 'Text' => 'Текст объявления 2', 'Href' ='http://www.site.ru/page{param1}?utm_content={phrase_id}' }, # Добавление объявления в группу { 'BannerID' => 0, 'CampaignID' => 1327837, 'AdGroupID' => 4571251, 'Title' => 'Заголовок объявления 3', 'Text' => 'Текст объявления 3', 'Href' ='http://www.site.ru/page{param2}?utm_content={phrase_id}' } ] ```