update

Изменяет параметры групп объявлений.

Узнайте больше

Ограничения

Для работы с Единой перфоманс-группой используется адрес https://api.direct.yandex.com/v501/.

Не более 1000 групп в одном вызове метода.

Не допускается изменение групп в архивных кампаниях.

Запрос

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

{
  "method": "update",
  "params": { /* params */
    "AdGroups": [{  /* AdGroupUpdateItem */
      "Id": (long), /* required */
      "Name": (string),
      "RegionIds": [(long), ... ],
      "NegativeKeywords": {  /* ArrayOfString */
        "Items": [(string), ... ] /* required */
      }, /* nillable */
      "NegativeKeywordSharedSetIds": { /* ArrayOfLong */
        "Items": [(long), ... ] /* required */
      }, /* nillable */
      "TrackingParams": (string),
      "MobileAppAdGroup": {  /* MobileAppAdGroupUpdate */
        "TargetDeviceType": [( "DEVICE_TYPE_MOBILE" | "DEVICE_TYPE_TABLET" ), ... ],
        "TargetCarrier": ( "WI_FI_ONLY" | "WI_FI_AND_CELLULAR" ),
        "TargetOperatingSystemVersion": (string)
      },
      "DynamicTextAdGroup": [{  /* DynamicTextAdGroupUpdate */
        "DomainUrl": (string) /* required */,
        "AutotargetingCategories" : [{  /* AutotargetingCategoriesUpdate */
          "Category" : ( "EXACT" | "ALTERNATIVE" | "COMPETITOR" | "BROADER" | "ACCESSORY" ) /* required */,
          "Value" : ( "YES" | "NO" ) /* required */
        }, ...]
      }, ...],
      "DynamicTextFeedAdGroup": {  /* DynamicTextFeedAdGroupUpdate*/
        "AutotargetingCategories" : [{  /* AutotargetingCategoriesUpdate */
          "Category" : ( "EXACT" | "ALTERNATIVE" | "COMPETITOR" | "BROADER" | "ACCESSORY" ) /* required */,
          "Value" : ( "YES" | "NO" ) /* required */
        }, ...]
      },
      "SmartAdGroup": {  /* SmartAdGroupUpdate */
        "AdTitleSource": (string), /* nillable */
        "AdBodySource": (string) /* nillable */
      },
      "TextAdGroupFeedParams" : {  /* TextAdGroupFeedParamsUpdate */
        "FeedId" : (long) /* required nillable */,
        "FeedCategoryIds" : { /* nillable */
          "Items" : [ (long) ] /* required */
        }
      },
      "UnifiedAdGroup" : {
        "OfferRetargeting" : ("YES"|"NO")
      }
    }, ... ] /* required */
  }
}

Параметр

Тип

Описание

Обяза- тельный

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

AdGroups

array of AdGroupUpdateItem

Группы, параметры которых требуется изменить.

Да

Структура AdGroupUpdateItem

Id

long

Идентификатор группы, параметры которой требуется изменить.

Да

Name

string

Название группы объявлений (от 1 до 255 символов).

Нет

RegionIds

array of long

Массив идентификаторов регионов, для которых показы включены или выключены. Массив должен содержать хотя бы один элемент.

Идентификатор 0 — показывать во всех регионах.

Минус перед идентификатором региона — выключить показы в данном регионе. Например [1,-219] — показывать для Москвы и Московской области, кроме Черноголовки. Минус-регионы нельзя использовать, если указан 0. Массив не должен состоять только из минус-регионов.
Справочник регионов можно получить с помощью метода Dictionaries.get.

Нет

NegativeKeywords

ArrayOfString, nillable

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

Внимание

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

Минус-фразу следует указывать без минуса перед первым словом.

Не более 7 слов в минус-фразе. Длина каждого слова — не более 35 символов. Суммарная длина минус-фраз в массиве — не более 4096 символов. Пробелы, дефисы и операторы не учитываются в суммарной длине.

Примечание

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

Нет

NegativeKeywordSharedSetIds

ArrayOfLong, nillable

Идентификаторы наборов минус-фраз. Не более 3 элементов в массиве.

Получить идентификаторы наборов можно с помощью метода NegativeKeywordSharedSets.get.

Внимание

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

Нет

TrackingParams

string

GET-параметры для отслеживания источников переходов на сайт, которые добавляются в ссылку всех объявлений группы (не более 1024 символов). Могут содержать подстановочные переменные.

Например: from=direct&ad={ad_id}

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

Нет

MobileAppAdGroup

MobileAppAdGroupUpdate

Параметры группы объявлений для рекламы мобильных приложений.

Нет

DynamicTextAdGroup

DynamicTextAdGroupUpdate

Параметры группы динамических объявлений.

Нет

DynamicTextFeedAdGroup

DynamicTextFeedAdGroupUpdate

Параметры группы динамических объявлений с подтипом FEED.

Нет

SmartAdGroup

SmartAdGroupUpdate

Параметры группы смарт-баннеров.

Нет

TextAdGroupFeedParams

TextAdGroupFeedParamsUpdate

Параметры группы текстово-графических объявлений.

Нет

UnifiedAdGroup

UnifiedAdGroupUpdate

Параметры единой перфоманс группы. См. Тип группы.

Нет

Структура MobileAppAdGroupUpdate

TargetDeviceType

array of DeviceTypeEnum

На каких устройствах показывать объявления:

  • DEVICE_TYPE_MOBILE — смартфоны;

  • DEVICE_TYPE_TABLET — планшеты.

Нет

TargetCarrier

CarrierEnum

По каким типам подключения к интернету показывать объявления:

  • WI_FI_ONLY — только по Wi-FI;
  • WI_FI_AND_CELLULAR — по мобильной связи и Wi-Fi.

Нет

TargetOperatingSystemVersion

string

Минимальная версия операционной системы, на которой может быть показано объявление. Например, 2.3.

Примечание

Если минимальная версия ОС в магазине приложений выше, чем заданная в параметре, то объявления будут показаны только для версий ОС как в магазине приложений или выше.

Нет

Структура DynamicTextAdGroup

DomainUrl

string

Доменное имя сайта, для которого требуется сгенерировать динамические объявления (не более 100 символов). Протокол указывать не нужно.

Да

AutotargetingCategories

array of AutotargetingCategoriesUpdateItem

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

Нет

Структура DynamicTextFeedAdGroupUpdate

AutotargetingCategories

array of AutotargetingCategoriesUpdateItem

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

Нет

Структура AutotargetingCategoriesUpdateItem

Category

AutotargetingCategoriesEnum

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

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

Да

Value

YesNoEnum

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

Да

Структура SmartAdGroupUpdate

AdTitleSource

string, nillable

Название элемента фида, из которого нужно брать заголовок объявления. Если не задано, заголовок генерируется автоматически.

Нет

AdBodySource

string, nillable

Название элемента фида, из которого нужно брать текст объявления. Если не задано, текст генерируется автоматически.

Нет

Структура TextAdGroupFeedParamsUpdate

FeedId

long, nillable

Идентификатор фида, на основе которого требуется сгенерировать текстово-графические объявления.

Нет

FeedCategoryIds

ArrayOfLong

Идентификаторы категорий товаров, на основе которых требуется сгенерировать текстово-графические объявления.

Если идентификаторы категорий не заданы, используются все категории из фида.

Нет

Структура UnifiedAdGroupUpdate

OfferRetargeting

YesNoEnum

Признак включения офферного ретаргетинга.

Нет

Ответ

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

{
  "result": {  /* result */
    "UpdateResults": [{  /* 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) / UpdateResponse (для SOAP)

UpdateResults

array of ActionResult

Результаты изменения параметров групп.

Структура ActionResult

Id

long

Идентификатор группы. Возвращается в случае отсутствия ошибок, см. раздел Операции над массивом объектов.

Warnings

array of ExceptionNotification

Предупреждения, возникшие при выполнении операции.

Errors

array of ExceptionNotification

Ошибки, возникшие при выполнении операции.