add

API версии 5. Справочник

Keywords: управление ключевыми фразами и автотаргетингами

add

Создает ключевые фразы и автотаргетинги.

Внимание.

В Рекламной сети Яндекса будет отключено ручное управление ставками. Подробнее.

22 апреля 2024 года будет закрыто создание новых кампаний на ручной стратегии: в методах add и update у кампаний TextCampaign и MobileAppCampaign в параметре Network.BiddingStrategyType перестанет поддерживаться стратегия MAXIMUM_COVERAGE. Также для таких кампаний будет нельзя использовать метод resume. Попытка использования будет возвращать ошибку валидации.
20 мая 2024 года будет закрыто редактирование ставок в активных кампаниях: в методе set перестанет поддерживаться параметр Bids.ContextBid (KeywordBids.NetworkBid). Попытка использования будет возвращать ошибку валидации.
Июнь 2024 года — будут остановлены активные кампании: попытка использования метода resume для кампаний со стратегией MAXIMUM_COVERAGE в параметре Network.BiddingStrategyType будет возвращать ошибку валидации, если не сменить стратегию на доступную. Впоследствии стратегия у таких остановленных и архивных кампаний будет изменена на WB_MAXIMUM_CLICKS (сами кампании запущены или разархивированы не будут).

Внимание. Метод не сохраняет дубликаты фраз, см. Дубликаты фраз.

Ставку или приоритет можно назначить в зависимости от того, какая стратегия выбрана в кампании:

Если в кампании настроена автоматическая стратегия, то можно указать параметр StrategyPriority: фразы с более высоким приоритетом по возможности получают больший объем трафика, а при недостатке бюджета отключаются в последнюю очередь.
Если в кампании настроена ручная стратегия, то можно указать параметр Bid, а если стратегия предусматривает независимое управление ставками в сетях — параметры Bid и ContextBid.

В случае если элемент входного массива содержит параметры, не соответствующие стратегии (например, приоритет при ручной стратегии), то значения этих параметров будут сохранены и будет выдано предупреждение.

Если в кампании настроена автоматическая стратегия, а при создании фразы заданы параметры Bid и/или ContextBid, то эти значения ставок не будут применены: в момент смены стратегии с автоматической на ручную будут заданы ставки, подобранные автоматическим алгоритмом.
Если в кампании настроена ручная стратегия, а при создании фразы задан параметр StrategyPriority, то в дальнейшем в момент смены стратегии на автоматическую заданное значение приоритета будет применено.
Если в кампании настроена ручная стратегия без независимого управления ставками в сетях, а при создании фразы задан параметр ContextBid, то в дальнейшем в момент смены стратегии на ручную с независимым управлением ставками заданное значение ставки будет применено.

Если стратегия предполагает назначение ставки, а ставка не указана, по умолчанию назначается:

для ключевой фразы — минимальная ставка;
для автотаргетинга для ставки ContextBid – ставка, рассчитанная на основе ставок по ключевым фразам в группе объявлений (в случае отсутствия фраз в группе — минимальная ставка).
для автотаргетинга для ставки Bid – автоматическая ставка. Если автоматическая ставка выключена – ставка, рассчитанная на основе ставок по ключевым фразам в группе объявлений (ручная ставка рассчитывается всегда, но используется только при выключенной автоставке). В случае отсутствия фраз в группе используется минимальная ставка.

Если стратегия предполагает назначение приоритета, а приоритет не указан, по умолчанию назначается средний приоритет.

Внимание.

Ставки и цены передаются через API Директа в виде целых чисел. Передаваемое значение представляет собой ставку или цену, умноженную на 1 000 000.
Все ставки и цены указываются в валюте рекламодателя.

По умолчанию все категории таргетинга включены.

Категории, для которых явно не указано значение "YES" или "NO", считаются включенными.

Ограничения

Не более 1000 объектов в одном вызове метода.

Не более 1 автотаргетинга в группе объявлений.

Не допускается добавление ключевых фраз в группу объявлений с типом CPM_BANNER_AD_GROUP и подтипом USER_PROFILE, а также в группу объявлений с типом DYNAMIC_TEXT_AD_GROUP.

Не допускается добавление автотаргетингов в группы объявлений с типом DYNAMIC_TEXT_AD_GROUP и CPM_BANNER_AD_GROUP.

Ограничение на количество ключевых фраз в группе объявлений для рекламодателя можно получить с помощью метода Clients.get или AgencyClients.get (элемент KEYWORDS_TOTAL_PER_ADGROUP массива Restrictions).

Ограничения на количество слов и символов в ключевой фразе см. в разделе Количественные ограничения помощи Директа.

Запрос

Структура запроса в формате JSON:

{
  "method": "add",
  "params": {  /* params */
    "Keywords": [{  /* KeywordAddItem */
      "Keyword": (string), /* required */
      "AdGroupId": (long), /* required */
      "Bid": (long),
      "AutotargetingSearchBidIsAuto" : ("YES" | "NO"),
      "ContextBid": (long),
      "StrategyPriority":  ( "LOW" | "NORMAL" | "HIGH" ),
      "UserParam1": (string),
      "UserParam2": (string),
      "AutotargetingCategories" : [{  /* AutotargetingCategoriesAddItem */
          "Category" : ("EXACT"|"ALTERNATIVE"|"COMPETITOR"|"BROADER"|"ACCESSORY") /* required */,
          "Value" : ("YES"|"NO") /* required */
      }, ...],
      "AutotargetingSettings" : {
        "Categories" : {
            "Exact" : ("YES"|"NO"),
            "Narrow" : ("YES"|"NO"),
            "Alternative" : ("YES"|"NO"),
            "Accessory" : ("YES"|"NO"),
            "Broader" : ("YES"|"NO")
        },
        "BrandOptions" : {
            "WithoutBrands" : ("YES"|"NO"),
            "WithAdvertiserBrand" : ("YES"|"NO"),
            "WithCompetitorsBrand" : ("YES"|"NO")
        }
      }
    }, ... ] /* required */
  }
}

Параметр Тип Описание Обяза-тельный

Структура params (для JSON) / AddRequest (для SOAP)

Keywords array of KeywordAddItem Ключевые фразы и автотаргетинги, которые требуется добавить. Да

Структура KeywordAddItem

AdGroupId long Идентификатор группы, в которую добавляется ключевая фраза или автотаргетинг. Да

Keyword

string

Ключевая фраза.

Может содержать минус-слова, которые указывают со знаком минус перед словом, например молния -гром -дождь.

Длина ключевой фразы — не более 4096 символов. Оператор «!» перед минус-словом не учитывается в длине фразы (последовательность «-!» считается как один символ).

Не более 7 слов в ключевой фразе, без учета стоп-слов и минус-слов. Каждое слово — не более 35 символов, без учета минуса перед минус-словом.

Примечание. Минус-слова, общие для всех ключевых фраз в группе объявлений, предпочтительно задавать в параметре группы .

Если указано значение ---autotargeting, будет создан автотаргетинг и появится возможность указать автоматическую ставку (AutotargetingSearchBidIsAuto).

Да

Bid

long

Ставка на поиске, умноженная на 1 000 000. Целое число. Только для ручной стратегии.

Указывается в валюте рекламодателя. Ограничения представлены в справочнике валют, который можно получить с помощью метода Dictionaries.get, указав в запросе имя справочника Currencies.

Нет

AutotargetingSearchBidIsAuto

YesNoEnum

Признак включения опции автоматической ставки.

Можно одновременно указать ручную ставку (Bid) и включить автоставку (AutotargetingSearchBidIsAuto). В этом случае будет работать автоставка, а ручная будет использоваться в случае отключения автоматической.

Если указана ручная ставка Bid: значение автоматической ставки (AutotargetingSearchBidIsAuto) будет выставлено NO, если в явном виде не прислано иное значение автоставки.

Если не указана ручная ставка Bid: значение автоматической ставки (AutotargetingSearchBidIsAuto) будет выставлено YES, если в явном виде не прислано иное значение автоставки.

Нет

ContextBid

long

Ставка в сетях, умноженная на 1 000 000. Целое число. Только для ручной стратегии с независимым управлением ставками в Рекламной сети.

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

Нет

StrategyPriority

PriorityEnum

Приоритет ключевой фразы или автотаргетинга: LOW, NORMAL или HIGH. Только для автоматической стратегии.

Нет

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

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

AutotargetingCategories

array of AutotargetingCategoriesAddItem

Категории таргетинга, которые требуется добавить.

Внимание.

Структура устарела и скоро перестанет поддерживаться. Нельзя одновременно передать AutotargetingCategories и AutotargetingSettings, вернется ошибка валидации.

Нет

AutotargetingSettings AutotargetingSettingsAddItem Настройки таргетинга, которые требуется добавить. Нет

Структура AutotargetingCategoriesAddItem

Category

AutotargetingCategoriesEnum

Категория таргетинга:

EXACT — целевые запросы. Рекламное объявление точно отвечает на запросы пользователя;
ALTERNATIVE — альтернативные запросы. Пользователь ищет продукт, который можно заменить рекламируемым. При этом объявление также может удовлетворить запрос;
COMPETITOR — запросы с упоминанием конкурентов. Поиск рекламируемого продукта у конкурентов;
BROADER — широкие запросы. Запросы с интересом к продукту, примером которого является рекламное предложение;
ACCESSORY — сопутствующие запросы. Запросы по продуктам, которые могут быть интересны вместе с рекламируемым товаром или услугой.

Внимание.

Поле устарело и скоро перестанет поддерживаться.

Настройки, заданные с помощью API, сконвертируются в веб-интерфейсе по следующим правилам:


API	Веб-интерфейс
Включенная категория EXACT.	Включенные категории «Целевые», «Узкие».
Включенная категория COMPETITOR (если это единственная включенная категория).	Включенная опция упоминания брендов «Конкуренты» + отключение остальных опций упоминания брендов + включение всех категорий.
Включенная категория COMPETITOR (если это не единственная включенная категория).	Включенная опция упоминания брендов «Конкуренты».
Выключенная категория COMPETITOR.	Выключенная опция упоминания брендов «Конкуренты».


API	Веб-интерфейс
Включенная категория EXACT.	Включенные категории «Целевые», «Узкие».
Включенная категория COMPETITOR (если это единственная включенная категория).	Включенная опция упоминания брендов «Конкуренты» + отключение остальных опций упоминания брендов + включение всех категорий.
Включенная категория COMPETITOR (если это не единственная включенная категория).	Включенная опция упоминания брендов «Конкуренты».
Выключенная категория COMPETITOR.	Выключенная опция упоминания брендов «Конкуренты».

Да

Value YesNoEnum Признак включения указанной категории таргетинга. По умолчанию включены все категории таргетинга. Да

Структура AutotargetingSettingsAddItem

Categories

AutotargetingSettingsCategoriesFieldNames

Категории таргетинга. Доступные опции:

Exact – целевые запросы. Рекламное объявление точно отвечает на запросы пользователя.
Narrow – узкие запросы. Рекламное объявление шире, чем запросы пользователя.
Alternative – альтернативные запросы. Пользователь ищет продукт, который можно заменить рекламируемым. При этом объявление также может удовлетворить запрос.
Accessory – сопутствующие запросы. Запросы по продуктам, которые могут быть интересны вместе с рекламируемым товаром или услугой.
Broader – широкие запросы. Запросы с интересом к продукту, примером которого является рекламное предложение.

Нет

BrandOptions

AutotargetingSettingsBrandOptionsFieldNames

Настройки брендовости. Доступные опции:

WithoutBrands – без упоминания брендов.
WithAdvertiserBrand – с упоминанием бренда рекламодателя.
WithCompetitorsBrand – с упоминанием брендов конкурентов.

Нет

Параметр Тип Описание Обяза-тельный

Структура params (для JSON) / AddRequest (для SOAP)

Keywords array of KeywordAddItem Ключевые фразы и автотаргетинги, которые требуется добавить. Да

Структура KeywordAddItem

AdGroupId long Идентификатор группы, в которую добавляется ключевая фраза или автотаргетинг. Да

Keyword

string

Ключевая фраза.

Может содержать минус-слова, которые указывают со знаком минус перед словом, например молния -гром -дождь.

Да

Bid

long

Ставка на поиске, умноженная на 1 000 000. Целое число. Только для ручной стратегии.

Нет

AutotargetingSearchBidIsAuto

YesNoEnum

Признак включения опции автоматической ставки.

Нет

ContextBid

long

Нет

StrategyPriority

PriorityEnum

Приоритет ключевой фразы или автотаргетинга: LOW, NORMAL или HIGH. Только для автоматической стратегии.

Нет

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

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

AutotargetingCategories

array of AutotargetingCategoriesAddItem

Категории таргетинга, которые требуется добавить.

Внимание.

Нет

AutotargetingSettings AutotargetingSettingsAddItem Настройки таргетинга, которые требуется добавить. Нет

Структура AutotargetingCategoriesAddItem

Category

AutotargetingCategoriesEnum

Категория таргетинга:

EXACT — целевые запросы. Рекламное объявление точно отвечает на запросы пользователя;
ALTERNATIVE — альтернативные запросы. Пользователь ищет продукт, который можно заменить рекламируемым. При этом объявление также может удовлетворить запрос;
COMPETITOR — запросы с упоминанием конкурентов. Поиск рекламируемого продукта у конкурентов;
BROADER — широкие запросы. Запросы с интересом к продукту, примером которого является рекламное предложение;
ACCESSORY — сопутствующие запросы. Запросы по продуктам, которые могут быть интересны вместе с рекламируемым товаром или услугой.

Внимание.

Поле устарело и скоро перестанет поддерживаться.

Настройки, заданные с помощью API, сконвертируются в веб-интерфейсе по следующим правилам:


API	Веб-интерфейс
Включенная категория EXACT.	Включенные категории «Целевые», «Узкие».
Включенная категория COMPETITOR (если это единственная включенная категория).	Включенная опция упоминания брендов «Конкуренты» + отключение остальных опций упоминания брендов + включение всех категорий.
Включенная категория COMPETITOR (если это не единственная включенная категория).	Включенная опция упоминания брендов «Конкуренты».
Выключенная категория COMPETITOR.	Выключенная опция упоминания брендов «Конкуренты».


API	Веб-интерфейс
Включенная категория EXACT.	Включенные категории «Целевые», «Узкие».
Включенная категория COMPETITOR (если это единственная включенная категория).	Включенная опция упоминания брендов «Конкуренты» + отключение остальных опций упоминания брендов + включение всех категорий.
Включенная категория COMPETITOR (если это не единственная включенная категория).	Включенная опция упоминания брендов «Конкуренты».
Выключенная категория COMPETITOR.	Выключенная опция упоминания брендов «Конкуренты».

Да

Структура AutotargetingSettingsAddItem

Categories

AutotargetingSettingsCategoriesFieldNames

Категории таргетинга. Доступные опции:

Exact – целевые запросы. Рекламное объявление точно отвечает на запросы пользователя.
Narrow – узкие запросы. Рекламное объявление шире, чем запросы пользователя.
Alternative – альтернативные запросы. Пользователь ищет продукт, который можно заменить рекламируемым. При этом объявление также может удовлетворить запрос.
Accessory – сопутствующие запросы. Запросы по продуктам, которые могут быть интересны вместе с рекламируемым товаром или услугой.
Broader – широкие запросы. Запросы с интересом к продукту, примером которого является рекламное предложение.

Нет

BrandOptions

AutotargetingSettingsBrandOptionsFieldNames

Настройки брендовости. Доступные опции:

WithoutBrands – без упоминания брендов.
WithAdvertiserBrand – с упоминанием бренда рекламодателя.
WithCompetitorsBrand – с упоминанием брендов конкурентов.

Нет

Ответ

Структура ответа в формате JSON:

{
  "result": {  /* result */
    "AddResults": [{  /* ActionResult */
      "Id": (long),
      "Warnings": [{  /* ExceptionNotification */
        "Code": (int), /* required */
        "Message": (string), /* required */
        "Details": (string)
      }, ...  ],
      "Errors": [{  /* ExceptionNotification */
        "Code": (int), /* required */
        "Message": (string), /* required */
        "Details": (string)
      }, ... ]
    }, ... ] /* required */
  }
}


Структура result (для JSON) / AddResponse (для SOAP)
Параметр	Тип	Описание
`AddResults`	array of ActionResult	Результаты добавления ключевых фраз и автотаргетингов.
Структура ActionResult
`Id`	long	Идентификатор созданной ключевой фразы или автотаргетинга. Возвращается в случае отсутствия ошибок, см. раздел Операции над массивом объектов.
`Warnings`	array of ExceptionNotification	Предупреждения, возникшие при выполнении операции.
`Errors`	array of ExceptionNotification	Ошибки, возникшие при выполнении операции.


Структура result (для JSON) / AddResponse (для SOAP)
Параметр	Тип	Описание
`AddResults`	array of ActionResult	Результаты добавления ключевых фраз и автотаргетингов.
Структура ActionResult
`Id`	long	Идентификатор созданной ключевой фразы или автотаргетинга. Возвращается в случае отсутствия ошибок, см. раздел Операции над массивом объектов.
`Warnings`	array of ExceptionNotification	Предупреждения, возникшие при выполнении операции.
`Errors`	array of ExceptionNotification	Ошибки, возникшие при выполнении операции.

Была ли статья полезна?

Расскажите, что вам не понравилось в статье:

Keywords: управление ключевыми фразами и автотаргетингами

delete

В этой статье

Ограничения Запрос Ответ

Keywords: управление ключевыми фразами и автотаргетингами

delete