update

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

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

Ограничения

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

Не допускается редактирование объявлений со статусом ARCHIVED, см. Статус и состояние объявления.

Запрос

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

{
  "method": "update",
  "params": { /* params */
    "Ads": [{  /* AdUpdateItem */
      "Id": (long), /* required */
      "TextAd": {  /* TextAdUpdate */
        "Title": (string),
        "Title2": (string), /* nillable */ 
        "Text": (string),
        "Href": (string), /* nillable */ 
        "AgeLabel": ( "AGE_0" | ... | "MONTHS_12" ),   
        "DisplayUrlPath": (string), /* nillable */ 
        "VCardId": (long), /* nillable */ 
        "AdImageHash": (string), /* nillable */ 
        "SitelinkSetId": (long), /* nillable */ 
        "CalloutSetting": {  /* AdExtensionSetting */
          "AdExtensions": [{  /* AdExtensionSettingItem */
            "AdExtensionId": (long), /* required */
            "Operation": ( "ADD" | "REMOVE" | "SET" ) /* required */
          }, ... ] /* required */
        }, /* nillable */
        "VideoExtension": {  /* VideoExtensionUpdateItem */
          "CreativeId": (long), /* nillable */ 
        },
        "PriceExtension": {  /* PriceExtensionUpdateItem */
          "Price": (long), 
          "OldPrice": (long), /* nillable */
          "PriceQualifier": ( "FROM" | "UP_TO" | "NONE" ),
          "PriceCurrency": ( "RUB" | "BYN" | "CHF" | "EUR" | "KZT" | "TRY" | "UAH" | "USD" )
        }, /* nillable */ 
        "TurboPageId": (long) /* nillable */ 
      },
      "DynamicTextAd": {  /* DynamicTextAdUpdate */
        "VCardId": (long), /* nillable */ 
        "AdImageHash": (string), /* nillable */ 
        "SitelinkSetId": (long), /* nillable */ 
        "CalloutSetting": {  /* AdExtensionSetting */
          "AdExtensions": [{  /* AdExtensionSettingItem */
            "AdExtensionId": (long), /* required */
            "Operation": ( "ADD" | "REMOVE" | "SET" ) /* required */
          }, ... ] /* required */
        }, /* nillable */
        "Text": (string)             
      },
      "MobileAppAd": {  /* MobileAppAdUpdate */
         "Title": (string),
         "Text": (string),
         "TrackingUrl": (string), /* nillable */ 
         "Action": ( "DOWNLOAD" | "GET" | "INSTALL" | "MORE" | "OPEN" | "UPDATE" | "PLAY" | "BUY_AUTODETECT" ),
         "AdImageHash": (string), /* nillable */
         "Features": [{  /* MobileAppAdFeatureItem */
           "Feature": ( "PRICE" | "ICON" | "CUSTOMER_RATING" | "RATINGS" ), /* required */
           "Enabled": ( "YES" | "NO" ) /* required */
         }, ... ],             
         "AgeLabel": ( "AGE_0" | ... | "AGE_18" )
      }, 
      "TextImageAd": {  /* TextImageAdUpdate */
        "AdImageHash": (string),
        "Href": (string), /* nillable */
        "TurboPageId": (long) /* nillable */
      },
      "MobileAppImageAd": {  /* MobileAppImageAdUpdate */
        "AdImageHash": (string),
        "TrackingUrl": (string) /* nillable */
      },
      "TextAdBuilderAd": {  /* TextAdBuilderAdUpdate */
        "Creative": { /* AdBuilderAdUpdateItem */
          "CreativeId": (long) /* required */
        }, 
        "Href": (string), /* nillable */
        "TurboPageId": (long) /* nillable */
      },
      "MobileAppAdBuilderAd": {  /* MobileAppAdBuilderAdUpdate */
        "Creative": { /* AdBuilderAdUpdateItem */
          "CreativeId": (long) /* required */
        }, 
        "TrackingUrl": (string) /* nillable */
      },
      "CpcVideoAdBuilderAd": {  /* CpcVideoAdBuilderAdUpdate */
        "Creative": { /* AdBuilderAdUpdateItem */
          "CreativeId": (long) /* required */
        }, 
        "Href": (string),  /* nillable */
        "TurboPageId": (long) /* nillable */
      },
      "CpmBannerAdBuilderAd": {  /* CpmBannerAdBuilderAdUpdate */
        "Creative": { /* AdBuilderAdUpdateItem */
          "CreativeId": (long) /* required */
        }, 
        "Href": (string), /* nillable */
        "TrackingPixels": { /* ArrayOfString */
          "Items": [(string), ... ] /* required */
        }, /* nillable */
        "TurboPageId": (long) /* nillable */
      }
    }, ... ] /* required */
  } 
}
Параметр Тип Описание Обязательный
Структура params (для JSON) / UpdateRequest (для SOAP)
Ads array of AdUpdateItem Объявления, параметры которых требуется изменить. Да
Структура AdUpdateItem
Id long Идентификатор объявления, параметры которого требуется изменить. Да
TextAd TextAdUpdate Параметры текстово-графического объявления. См. Тип объявления. Либо TextAd, либо MobileAppAd, либо DynamicTextAd, либо TextImageAd, либо MobileAppImageAd, либо TextAdBuilderAd, либо MobileAppAdBuilderAd, либо CpcVideoAdBuilderAd, либо CpmBannerAdBuilderAd
DynamicTextAd DynamicTextAdUpdate Параметры динамического объявления.
MobileAppAd MobileAppAdUpdate Параметры объявления для рекламы мобильных приложений.
TextImageAd TextImageAdUpdate Параметры графического объявления, созданного на основе изображения (в группе текстово-графических объявлений).
MobileAppImageAd MobileAppImageAdUpdate Параметры графического объявления, созданного на основе изображения (в группе для рекламы мобильных приложений).
TextAdBuilderAd TextAdBuilderAdUpdate Параметры графического объявления, созданного на основе креатива (в группе текстово-графических объявлений).
MobileAppAdBuilderAd MobileAppAdBuilderAdUpdate Параметры графического объявления, созданного на основе креатива (в группе для рекламы мобильных приложений).
CpcVideoAdBuilderAd CpcVideoAdBuilderAdUpdate Параметры видеообъявления (в кампании с типом «Текстово-графические объявления»).
CpmBannerAdBuilderAd CpmBannerAdBuilderAdUpdate Параметры медийного объявления.
Структура TextAdUpdate
Title string

Заголовок 1.

Не более 35 символов без учета «узких» плюс не более 15 «узких» символов. Каждое слово не более 22 символов. В случае использования шаблона символы # не учитываются в длине.

Нет
Title2 string, nillable

Заголовок 2.

Не более 30 символов без учета «узких» плюс не более 15 «узких» символов. Каждое слово не более 22 символов. В случае использования шаблона символы # не учитываются в длине.

Нет
Text string

Текст объявления.

Не более 81 символа без учета «узких» плюс не более 15 «узких» символов. Каждое слово не более 23 символов. В случае использования шаблона символы # не учитываются в длине.

Нет
Href string, nillable

Ссылка на сайт рекламодателя. Не более 1024 символов. В случае использования шаблона символы # не учитываются в длине.

Должна содержать протокол и доменное имя. Может содержать подстановочные переменные.

Нет
AgeLabel AgeLabelEnum Возрастная категория.

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

Нет
DisplayUrlPath string, nillable

Отображаемая ссылка. Допускается только при наличии параметра Href. Не более 20 символов. В случае использования шаблона символы # не учитываются в длине.

Может содержать буквы, цифры, символы -, №, /, %, #. Запрещены пробел, символ _, двойные символы --, //.

См. раздел Отображаемая ссылка помощи Директа.

Нет
VCardId long, nillable Идентификатор виртуальной визитки. Визитка должна принадлежать той же кампании, что и объявление. Нет
AdImageHash string, nillable

Хэш изображения.

Для текстово-графических объявлений подходят только изображения с типом REGULAR и WIDE, см. Тип изображения.
Нет
SitelinkSetId long, nillable Идентификатор набора быстрых ссылок. Допускается только при наличии параметра Href или TurboPageId. Нет
CalloutSetting AdExtensionSetting, nillable

Уточнения к объявлению:

  • Чтобы внести изменения в существующий набор уточнений, используйте типы действия ADD и REMOVE (см. описание параметра Operation).

  • Чтобы заменить существующий набор уточнений новым набором, используйте тип действия SET.

  • Чтобы отвязать все уточнения, передайте значение nil (null).
Нет
VideoExtension VideoExtensionUpdateItem

Видеодополнение.

См. раздел Видеодополнения помощи Директа.

Нет
PriceExtension PriceExtensionUpdateItem, nillable Цена в объявлении. Нет
TurboPageId long, nillable Идентификатор Турбо-страницы. Нет
Структура AdExtensionSetting
AdExtensions array of AdExtensionSettingItem Расширения, которые нужно привязать к объявлению или отвязать от объявления. Да
Структура AdExtensionSettingItem
AdExtensionId long Идентификатор расширения. Да
Operation AdExtensionTypeEnum Тип действия над набором расширений:
  • ADD — привязать расширение к объявлению;

  • REMOVE — отвязать расширение от объявления;

  • SET — заменить набор расширений и привязать расширение к объявлению в составе нового набора. Тип SET несовместим с ADD и REMOVE: для всех элементов в массиве AdExtensions должен быть указан тип SET.

См. Примеры.

Да
Структура VideoExtensionUpdateItem
CreativeId long, nillable

Идентификатор креатива.

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

Да
Структура PriceExtensionUpdateItem
Price long

Цена товара или услуги, умноженная на 1 000  000. Целое число, кратное 10 000 (что соответствует цене с двумя знаками после запятой). Максимальное значение — 10 000 000 000 000 000.

Нет
OldPrice long, nillable Старая цена товара или услуги, умноженная на 1 000  000. Целое число, кратное 10 000. Старая цена должна быть строго меньше цены. Нет
PriceQualifier PriceQualifierEnum

Текстовое пояснение к цене:

  • FROM — «от».
  • UP_TO — «до».
  • NONE — нет пояснения.
Нет
PriceCurrency PriceCurrencyEnum Валюта, в которой указана цена. Нет
Структура DynamicTextAdUpdate
VCardId long, nillable Идентификатор виртуальной визитки. Визитка должна принадлежать той же кампании, что и объявление. Нет
AdImageHash string, nillable

Хэш изображения.

Для динамических объявлений подходят только изображения с типом REGULAR и WIDE, см. Тип изображения.

Нет
SitelinkSetId long, nillable Идентификатор набора быстрых ссылок. Нет
CalloutSetting AdExtensionSetting, nillable

Уточнения к объявлению:

  • Чтобы внести изменения в существующий набор уточнений, используйте типы действия ADD и REMOVE (см. описание параметра Operation).

  • Чтобы заменить существующий набор уточнений новым набором, используйте тип действия SET.

  • Чтобы отвязать все уточнения, передайте значение nil (null).
Нет
Text string

Текст объявления.

Не более 81 символа без учета «узких» плюс не более 15 «узких» символов. Каждое слово не более 23 символов. В случае использования шаблона символы # не учитываются в длине.

Нет
Структура MobileAppAdUpdate
Title string

Заголовок.

Не более 33 символов с учетом «узких». Каждое слово не более 22 символов. В случае использования шаблона символы # не учитываются в длине.

Нет
Text string

Текст объявления.

Не более 75 символов с учетом «узких». Каждое слово не более 23 символов. В случае использования шаблона символы # не учитываются в длине.

Нет
TrackingUrl string, nillable Трекинговая ссылка для отслеживания установок приложения. Не более 1024 символов. Должна содержать протокол и доменное имя. Нет
Action MobileAppAdActionEnum

Надпись на кнопке:

  • DOWNLOAD — «Загрузить»

  • GET — «Скачать»

  • INSTALL — «Установить»

  • MORE — «Подробнее»

  • OPEN — «Открыть»

  • UPDATE — «Обновить»

  • PLAY — «Играть»

  • BUY_AUTODETECT — надпись зависит о цены приложения: «Купить», если цена отлична от нуля, или «Бесплатно», если цена равна нулю.

Нет
AdImageHash string, nillable

Хэш изображения.

Для рекламы мобильных приложений подходят только изображения с типом WIDE, см. Тип изображения.

Нет
Features array of MobileAppAdFeatureItem Дополнения, которые требуется автоматически загружать из магазина приложений и отображать в объявлении. Нет
AgeLabel MobAppAgeLabelEnum Возрастное ограничение. Нет
Структура MobileAppAdFeatureItem
Feature MobileAppFeatureEnum

Тип дополнения:

  • PRICE — цена;
  • ICON — иконка;
  • CUSTOMER_RATING — рейтинг;
  • RATINGS — количество оценок (отображается, только если включено отображение рейтинга).

Если тип дополнения отсутствует в массиве Features, дополнение не отображается.

Да
Enabled YesNoEnum

Отображать ли дополнение в объявлении.

Примечание.
  • Если дополнение не удалось загрузить из магазина приложений, для него допустимо значение YES, однако это дополнение не отображается при показе объявления.
  • Количество оценок отображается только вместе с рейтингом: если для типа CUSTOMER_RATING задано NO, а для RATINGS — YES, количество оценок не отображается.
Да
Структура TextImageAdUpdate
AdImageHash string

Хэш изображения.

Для графических объявлений подходят только изображения с типом FIXED_IMAGE, см. Тип изображения.

Нет
Href string, nillable

Ссылка на сайт рекламодателя. Не более 1024 символов. В случае использования шаблона символы # не учитываются в длине.

Должна содержать протокол и доменное имя. Может содержать подстановочные переменные.

Нет
TurboPageId long, nillable Идентификатор Турбо-страницы. Нет
Структура MobileAppImageAdUpdate
AdImageHash string

Хэш изображения.

Для графических объявлений подходят только изображения с типом FIXED_IMAGE, см. Тип изображения.

Нет
TrackingUrl string, nillable Трекинговая ссылка для отслеживания установок приложения. Не более 1024 символов. Должна содержать протокол и доменное имя. Нет
Структура TextAdBuilderAdUpdate
Creative AdBuilderAdUpdateItem

Креатив, созданный в конструкторе креативов.

См. раздел Конструктор креативов для графических объявлений помощи Директа.

Нет
Href string, nillable

Ссылка на сайт рекламодателя. Не более 1024 символов. В случае использования шаблона символы # не учитываются в длине.

Должна содержать протокол и доменное имя. Может содержать подстановочные переменные.

Нет
TurboPageId long, nillable Идентификатор Турбо-страницы. Нет
Структура MobileAppAdBuilderAdUpdate
Creative AdBuilderAdUpdateItem

Креатив, созданный в конструкторе креативов.

См. раздел Конструктор креативов для графических объявлений помощи Директа.

Нет
TrackingUrl string, nillable Трекинговая ссылка для отслеживания установок приложения. Не более 1024 символов. Должна содержать протокол и доменное имя. Нет
Структура CpcVideoAdBuilderAdUpdate
Creative AdBuilderAdUpdateItem

Креатив, созданный в конструкторе креативов.

См. раздел Видеообъявления / Конструктор креативов помощи Директа.

Нет
Href string, nillable

Ссылка на сайт рекламодателя. Не более 1024 символов. В случае использования шаблона символы # не учитываются в длине.

Должна содержать протокол и доменное имя. Может содержать подстановочные переменные.

Нет
TurboPageId long, nillable Идентификатор Турбо-страницы. Нет
Структура CpmBannerAdBuilderAdUpdate
Creative AdBuilderAdUpdateItem

Креатив, загруженный в веб-интерфейсе или созданный в конструкторе креативов.

См. раздел Создание медийной кампании помощи Директа.

Нет
Href string, nillable

Ссылка на сайт рекламодателя. Не более 1024 символов. В случае использования шаблона символы # не учитываются в длине.

Должна содержать протокол и доменное имя. Может содержать подстановочные переменные.

Нет
TrackingPixels ArrayOfString, nillable Может содержать не более двух строк:
  • Пиксель Яндекс.Аудиторий — см. раздел Пиксель помощи Яндекс.Аудиторий.
  • Счетчик показов ADFOX. В счетчике показов обязательно должен быть макрос %random% или %aw_random%.

Длина каждой строки не более 1024 символов.

Нет
TurboPageId long, nillable Идентификатор Турбо-страницы. Нет
Структура AdBuilderAdUpdateItem
CreativeId long

Идентификатор креатива.

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

Да

Ответ

Структура ответа в формате 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

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

Примеры

Внесение изменений в набор расширений к объявлению

К объявлению были привязаны уточнения с идентификаторами 111, 112, 113.

После выполнения запроса к объявлению будут привязаны уточнения с идентификаторами 111, 112, 114, 115.

{
  "method": "update",
  "params": {
    "Ads": [{
      "Id": 7654321,
      "TextAd": {
        "CalloutSetting": {
          "AdExtensions": [{
            "AdExtensionId": 114,
            "Operation": "ADD"
          },
          {
            "AdExtensionId": 115,
            "Operation": "ADD"
          },
          {
            "AdExtensionId": 113,
            "Operation": "REMOVE"
          }]
        }  
      }
    }]
  }
}
Замена набора расширений

К объявлению были привязаны уточнения с идентификаторами 111, 112, 113.

После выполнения запроса к объявлению будут привязаны уточнения с идентификаторами 113, 114.

{
  "method": "update",
  "params": {
    "Ads": [{
      "Id": 7654321,
      "TextAd": {
        "CalloutSetting": {
          "AdExtensions": [{
            "AdExtensionId": 113,
            "Operation": "SET"
          },
          {
            "AdExtensionId": 114,
            "Operation": "SET"
          }]
        }  
      }
    }]
  }
}