update

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

  1. Ограничения
  2. Запрос
  3. Ответ

Ограничения

Для работы с Единой перфоманс-группой используется адрес 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 Признак включения офферного ретаргетинга. Нет
Параметр Тип Описание Обяза- тельный
Структура 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

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

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

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

Errors array of ExceptionNotification

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