CreateOrUpdateBanners
Создает объявление и фразы или изменяет существующее объявление и фразы.
Метод отключен. Используйте API версии 5.
Информацию о соответствии методов в версиях 4 и 5 см. в Руководстве по переходу.
Для метода существует версия CreateOrUpdateBanners (Live).
Если кампания активна, добавленные и измененные объявления автоматически отправляются на модерацию. Для кампаний в статусе «Черновик» отправить объявление на модерацию можно с помощью метода ModerateBanners.
Ограничения
Группы из нескольких объявлений в версии 4 не поддерживаются. Для работы с такими группами используйте метод CreateOrUpdateBanners (Live).
В одном вызове метода можно передать не более 1000 объявлений.
Для одной кампании можно вызвать метод не более 1000 раз в сутки. При вызове метода расходуются баллы (см. Балльные ограничения). Если баллов недостаточно, возвращается сообщение об ошибке 152.
Кампания может иметь не более 1000 объявлений. Количество ключевых фраз в объявлении — не более 200.
Чтобы обновить только цены за клик, рекомендуется использовать метод UpdatePrices, при вызове которого баллы не расходуются.
Входные данные
Ниже показана структура входных данных в формате JSON.
{
"method": "CreateOrUpdateBanners",
"param": [
{ /* BannerInfo */
"BannerID": (long),
"CampaignID": (int),
"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)
}
}
...
],
"Sitelinks": [
{ /* Sitelink */
"Title": (string),
"Href": (string)
}
...
],
"MinusKeywords": [
(string)
...
]
}
...
]
}Ниже приведено описание параметров.
| Параметр | Описание | Требуется |
| Объект BannerInfo | ||
|---|---|---|
BannerID | Идентификатор объявления. Для создания объявления задают 0, для изменения параметров объявления указывают его идентификатор. | Да |
CampaignID | Идентификатор кампании. | Да |
Title | Заголовок объявления (до 33 символов, включая пробелы и знаки препинания). | Да |
Text | Текст объявления (до 75 символов, включая пробелы и знаки препинания). | Да |
Href | Ссылка на сайт рекламодателя. Может содержать подстановочные переменные (см. раздел Ссылки на сайт). | Один из параметров — Href или ContactInfo |
ContactInfo | Объект ContactInfo с контактными данными рекламодателя (визитка). | |
Geo | Идентификаторы регионов, для которых показы включены или выключены. Идентификатор 0 или пустая строка — показывать во всех регионах (предустановленное значение). Чтобы выключить показ в регионе, перед идентификатором региона ставят минус, например «1,-219» — показывать для Москвы и Московской области, кроме Черноголовки. Регионы с минусом нельзя использовать, если указан нулевой регион. Также параметр не должен состоять только из минус-регионов. Полный список регионов можно получить с помощью метода GetRegions. | Да |
Phrases | Массив объектов BannerPhraseInfo, содержащих информацию о фразах. У объявления должна присутствовать по меньшей мере одна фраза. Количество фраз в объявлении — не более 200. | Да |
Sitelinks | Массив объектов Sitelink с быстрыми ссылками. Массив должен содержать от 1 до 4 объектов Sitelink или отсутствовать. | Нет |
MinusKeywords | Массив минус-фраз, общих для всех ключевых фраз группы объявлений. Минус-фразу следует указывать без минуса перед первым словом. Не более 7 слов в минус-фразе. Длина каждого слова — не более 35 символов. Суммарная длина минус-фраз в массиве — не более 4096 символов. Оператор «!» или «+» перед словом не учитывается в суммарной длине. Примечание. Минус-фразы, общие для всех групп в кампании, предпочтительно задавать в одноименном параметре кампании. | Нет |
| Объект 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. Формат строки: Например, строка Режим может состоять из нескольких строк указанного формата, например: " Круглосуточный режим работы задается строкой | Да |
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 | Ставка на поиске Яндекса (у. е.). Предустановленное ограничение — 50 у. е. Требуется, только если для кампании выбрана стратегия с ручным управлением ставками. | Для ручных стратегий |
AutoBudgetPriority | Приоритет фразы при использовании автоматических стратегий. Возможные значения:
| Для стратегии WeeklyBudget |
ContextPrice | Ставка в Рекламной сети Яндекса (у. е.). Ставку можно задавать в следующих случаях:
| Для стратегии IndependentControl |
AutoBroker | Включить/выключить автоброкер. Параметр не используется, переданное значение игнорируется. | Нет |
UserParams | Объект PhraseUserParams. Содержит значения подстановочных переменных для формирования ссылки на сайт (см. раздел Ссылки на сайт). | Нет |
| Объект PhraseUserParams | ||
Param1 | Значение подстановочной переменной | При использовании подстановочных переменных в Href |
Param2 | Значение подстановочной переменной | |
| Объект Sitelink | ||
Title | Текст быстрой ссылки (не более 30 символов). Суммарная длина текстов всех быстрых ссылок — не более 66 символов. | Да |
Href | Адрес быстрой ссылки. Может содержать подстановочные переменные (см. раздел Ссылки на сайт). Внимание. В быстрых ссылках подстановка значений переменных {campaign_id}, {ad_id}, {banner_id}, {phrase_id} гарантируется только при наличии этих же переменных в основной ссылке объявления. | Да |
| Параметр | Описание | Требуется |
| Объект BannerInfo | ||
|---|---|---|
BannerID | Идентификатор объявления. Для создания объявления задают 0, для изменения параметров объявления указывают его идентификатор. | Да |
CampaignID | Идентификатор кампании. | Да |
Title | Заголовок объявления (до 33 символов, включая пробелы и знаки препинания). | Да |
Text | Текст объявления (до 75 символов, включая пробелы и знаки препинания). | Да |
Href | Ссылка на сайт рекламодателя. Может содержать подстановочные переменные (см. раздел Ссылки на сайт). | Один из параметров — Href или ContactInfo |
ContactInfo | Объект ContactInfo с контактными данными рекламодателя (визитка). | |
Geo | Идентификаторы регионов, для которых показы включены или выключены. Идентификатор 0 или пустая строка — показывать во всех регионах (предустановленное значение). Чтобы выключить показ в регионе, перед идентификатором региона ставят минус, например «1,-219» — показывать для Москвы и Московской области, кроме Черноголовки. Регионы с минусом нельзя использовать, если указан нулевой регион. Также параметр не должен состоять только из минус-регионов. Полный список регионов можно получить с помощью метода GetRegions. | Да |
Phrases | Массив объектов BannerPhraseInfo, содержащих информацию о фразах. У объявления должна присутствовать по меньшей мере одна фраза. Количество фраз в объявлении — не более 200. | Да |
Sitelinks | Массив объектов Sitelink с быстрыми ссылками. Массив должен содержать от 1 до 4 объектов Sitelink или отсутствовать. | Нет |
MinusKeywords | Массив минус-фраз, общих для всех ключевых фраз группы объявлений. Минус-фразу следует указывать без минуса перед первым словом. Не более 7 слов в минус-фразе. Длина каждого слова — не более 35 символов. Суммарная длина минус-фраз в массиве — не более 4096 символов. Оператор «!» или «+» перед словом не учитывается в суммарной длине. Примечание. Минус-фразы, общие для всех групп в кампании, предпочтительно задавать в одноименном параметре кампании. | Нет |
| Объект 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. Формат строки: Например, строка Режим может состоять из нескольких строк указанного формата, например: " Круглосуточный режим работы задается строкой | Да |
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 | Ставка на поиске Яндекса (у. е.). Предустановленное ограничение — 50 у. е. Требуется, только если для кампании выбрана стратегия с ручным управлением ставками. | Для ручных стратегий |
AutoBudgetPriority | Приоритет фразы при использовании автоматических стратегий. Возможные значения:
| Для стратегии WeeklyBudget |
ContextPrice | Ставка в Рекламной сети Яндекса (у. е.). Ставку можно задавать в следующих случаях:
| Для стратегии IndependentControl |
AutoBroker | Включить/выключить автоброкер. Параметр не используется, переданное значение игнорируется. | Нет |
UserParams | Объект PhraseUserParams. Содержит значения подстановочных переменных для формирования ссылки на сайт (см. раздел Ссылки на сайт). | Нет |
| Объект PhraseUserParams | ||
Param1 | Значение подстановочной переменной | При использовании подстановочных переменных в Href |
Param2 | Значение подстановочной переменной | |
| Объект Sitelink | ||
Title | Текст быстрой ссылки (не более 30 символов). Суммарная длина текстов всех быстрых ссылок — не более 66 символов. | Да |
Href | Адрес быстрой ссылки. Может содержать подстановочные переменные (см. раздел Ссылки на сайт). Внимание. В быстрых ссылках подстановка значений переменных {campaign_id}, {ad_id}, {banner_id}, {phrase_id} гарантируется только при наличии этих же переменных в основной ссылке объявления. | Да |
Результирующие данные
При успешном выполнении метод возвращает массив, содержащий идентификаторы созданных/обновленных баннеров, как показано в следующем примере.
{
"data": [33823946,33823947]
}Примеры входных данных
Python
[
{
'BannerID': 2571700,
'CampaignID': 1327837,
'Title': 'Banner title',
'Text': 'Banner text',
'Href': 'http://www.client.ru/banner{param1}?page={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': 'market-click2.ya.ru/?q=qu&action=1'
},
{
'Title': u'Доп. ссылка 2',
'Href': 'market-click2.ya.ru/?q=qu&action=2'
},
{
'Title': u'Доп. ссылка 3',
'Href': 'market-click2.ya.ru/?q=qu&action=3'
}
],
'MinusKeywords': ['ice','cream']
}
]PHP
array(
array(
'BannerID' => 2571700,
'CampaignID' => 1327837,
'Title' => 'Banner title',
'Text' => 'Banner text',
'Href' => 'http://www.client.ru/bannerarray(param1)?page=array(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' => 'market-click2.ya.ru/?q=qu&action=1'
),
array(
'Title' => 'Доп. ссылка 2',
'Href' => 'market-click2.ya.ru/?q=qu&action=2'
),
array(
'Title' => 'Доп. ссылка 3',
'Href' => 'market-click2.ya.ru/?q=qu&action=3'
)
),
'MinusKeywords' => array('ice','cream')
)
)Perl
[
{
'BannerID' => 2571700,
'CampaignID' => 1327837,
'Title' => 'Banner title',
'Text' => 'Banner text',
'Href' => 'http://www.client.ru/banner{param1}?page={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' => 'market-click2.ya.ru/?q=qu&action=1'
},
{
'Title' => 'Доп. ссылка 2',
'Href' => 'market-click2.ya.ru/?q=qu&action=2'
},
{
'Title' => 'Доп. ссылка 3',
'Href' => 'market-click2.ya.ru/?q=qu&action=3'
}
],
'MinusKeywords' => ['ice','cream']
}
]