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 | На каких устройствах показывать объявления:
| Нет |
TargetCarrier | CarrierEnum | По каким типам подключения к интернету показывать объявления:
| Нет |
TargetOperatingSystemVersion | string | Минимальная версия операционной системы, на которой может быть показано объявление. Например, 2.3. Примечание. Если минимальная версия ОС в магазине приложений выше, чем заданная в параметре, то объявления будут показаны только для версий ОС как в магазине приложений или выше. | Нет |
Структура DynamicTextAdGroup | |||
DomainUrl | string | Доменное имя сайта, для которого требуется сгенерировать динамические объявления (не более 100 символов). Протокол указывать не нужно. | Да |
AutotargetingCategories | array of AutotargetingCategoriesUpdateItem | Категории таргетинга, которые требуется добавить. | Нет |
Структура DynamicTextFeedAdGroupUpdate | |||
AutotargetingCategories | array of AutotargetingCategoriesUpdateItem | Категории таргетинга, которые требуется добавить. | Нет |
Структура AutotargetingCategoriesUpdateItem | |||
Category | AutotargetingCategoriesEnum | Категория таргетинга:
| Да |
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 | На каких устройствах показывать объявления:
| Нет |
TargetCarrier | CarrierEnum | По каким типам подключения к интернету показывать объявления:
| Нет |
TargetOperatingSystemVersion | string | Минимальная версия операционной системы, на которой может быть показано объявление. Например, 2.3. Примечание. Если минимальная версия ОС в магазине приложений выше, чем заданная в параметре, то объявления будут показаны только для версий ОС как в магазине приложений или выше. | Нет |
Структура DynamicTextAdGroup | |||
DomainUrl | string | Доменное имя сайта, для которого требуется сгенерировать динамические объявления (не более 100 символов). Протокол указывать не нужно. | Да |
AutotargetingCategories | array of AutotargetingCategoriesUpdateItem | Категории таргетинга, которые требуется добавить. | Нет |
Структура DynamicTextFeedAdGroupUpdate | |||
AutotargetingCategories | array of AutotargetingCategoriesUpdateItem | Категории таргетинга, которые требуется добавить. | Нет |
Структура AutotargetingCategoriesUpdateItem | |||
Category | AutotargetingCategoriesEnum | Категория таргетинга:
| Да |
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 | Ошибки, возникшие при выполнении операции. |