CreateOrUpdateBanners

Создает объявление и фразы или изменяет существующее объявление и фразы.

Внимание.

Метод отключен. Используйте API версии 5.

Информацию о соответствии методов в версиях 4 и 5 см. в Руководстве по переходу.

Для метода существует версия CreateOrUpdateBanners (Live).

Если кампания активна, добавленные и измененные объявления автоматически отправляются на модерацию. Для кампаний в статусе «Черновик» отправить объявление на модерацию можно с помощью метода ModerateBanners.

Ограничения

Внимание. Метод поддерживает только текстово-графические объявления. Для работы с объявлениями всех типов используйте сервис Ads API версии 5. Подробнее о типах объявлений...

Группы из нескольких объявлений в версии 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. Да
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.

Формат строки:

"день_с;день_по;час_с;минуты_с;час_до;мин_до"

Например, строка "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

Ставка на поиске Яндекса (у. е.). Предустановленное ограничение — 50 у. е. Требуется, только если для кампании выбрана стратегия с ручным управлением ставками.

Для ручных стратегий
AutoBudgetPriority

Приоритет фразы при использовании автоматических стратегий. Возможные значения:

  • Low — низкий приоритет;
  • Medium — средний приоритет;
  • High — высокий приоритет.
Для стратегии WeeklyBudget
ContextPrice

Ставка в Рекламной сети Яндекса (у. е.). Ставку можно задавать в следующих случаях:

  1. На поиске используется стратегия IndependentControl. Эту стратегию можно выбрать только через веб-интерфейс Директа.
  2. На поиске используется любая ручная стратегия и фраза отключена за низкий CTR.

    Для новых фраз данное условие не актуально, поскольку фразы больше не отключаются за низкий CTR.

Для стратегии IndependentControl
AutoBroker Включить/выключить автоброкер. Параметр не используется, переданное значение игнорируется. Нет
UserParams

Объект PhraseUserParams. Содержит значения подстановочных переменных для формирования ссылки на сайт (см. раздел Ссылки на сайт).

Нет
Объект PhraseUserParams
Param1

Значение подстановочной переменной {param1}. Не более 255 байт.

При использовании подстановочных переменных в Href
Param2

Значение подстановочной переменной {param2}. Не более 255 байт.

Результирующие данные

При успешном выполнении метод возвращает массив, содержащий идентификаторы созданных/обновленных баннеров, как показано в следующем примере.

{
   "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']
   }
]