update

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

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

Ограничения

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

Не более 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" | "UZS" )
        }, /* nillable */
        "TurboPageId": (long), /* nillable */
        "BusinessId": (long), /* nillable */
        "PreferVCardOverBusiness": ( "YES" | "NO" ),
        "ErirAdDescription" : (string) /* nillable */
      },
      "TextImageAd": {  /* TextImageAdUpdate */
        "AdImageHash": (string),
        "Href": (string), /* nillable */
        "TurboPageId": (long), /* nillable */
        "ErirAdDescription" : (string) /* nillable */
      },
      "TextAdBuilderAd": {  /* TextAdBuilderAdUpdate */
        "Creative": { /* AdBuilderAdUpdateItem */
          "CreativeId": (long) /* required */
        },
        "Href": (string), /* nillable */
        "TurboPageId": (long), /* nillable */
        "ErirAdDescription" : (string) /* nillable */
      },
      "CpmBannerAdBuilderAd": {  /* CpmBannerAdBuilderAdUpdate */
        "Creative": { /* AdBuilderAdUpdateItem */
          "CreativeId": (long) /* required */
        },
        "Href": (string), /* nillable */
        "TrackingPixels": { /* ArrayOfString */
          "Items": [(string), ... ] /* required */
        }, /* nillable */
        "TurboPageId": (long), /* nillable */
        "ErirAdDescription" : (string) /* nillable */
      },
      "CpmVideoAdBuilderAd": {  /* CpmVideoAdBuilderAdUpdate */
        "Creative": { /* AdBuilderAdUpdateItem */
          "CreativeId": (long) /* required */
        },
        "Href": (string),  /* nillable */
        "TrackingPixels": { /* ArrayOfString */
          "Items": [(string), ... ] /* required */
        }, /* nillable */
        "TurboPageId": (long),
        "ErirAdDescription" : (string) /* nillable */
      },
      "ShoppingAd" : {
          "SitelinkSetId" : (long) /* nillable */,
          "CalloutSetting" : { /* nillable */
            "AdExtensions" : [{ /* required */
                "AdExtensionId" : (long) /* required */,
                "Operation" : ("ADD"|"REMOVE"|"SET") /* required */
            }, ... ]
          },
          "BusinessId" : (long) /* nillable */,
          "FeedFilterConditions" : { /* nillable */
            "Items" : [{ /* required */
                "Operand" : (string) /* required */,
                "Operator" : ("CONTAINS_ANY"|"EQUALS_ANY"|"EXISTS"|"GREATER_THAN"|"IN_RANGE"|"LESS_THAN"|"NOT_CONTAINS_ALL") /* required */,
                "Arguments" : [ (string) ] /* required */
            }, ... ]
          },
          "TitleSources" : { /* nillable */
              "Items" : [ (string) ] /* required */
          },
          "TextSources" : { /* nillable */
              "Items" : [ (string) ] /* required */
          },
          "DefaultTexts" : [ (string) ]
      },
      "ListingAd" : {
          "SitelinkSetId" : (long) /* nillable */,
          "CalloutSetting" : { /* nillable */
            "AdExtensions" : [{ /* required */
                "AdExtensionId" : (long) /* required */,
                "Operation" : ("ADD"|"REMOVE"|"SET") /* required */
            }, ... ]
          },
          "BusinessId" : (long) /* nillable */,
          "FeedFilterConditions" : { /* nillable */
            "Items" : [{ /* required */
                "Operand" : (string) /* required */,
                "Operator" : ("CONTAINS_ANY"|"EQUALS_ANY"|"EXISTS"|"GREATER_THAN"|"IN_RANGE"|"LESS_THAN"|"NOT_CONTAINS_ALL") /* required */,
                "Arguments" : [ (string) ] /* required */
            }, ... ]
          },
          "TitleSources" : { /* nillable */
              "Items" : [ (string) ] /* required */
          },
          "TextSources" : { /* nillable */
              "Items" : [ (string) ] /* required */
          },
          "DefaultTexts" : [ (string) ]
      }
    }, ... ] /* required */
  }
}

Параметр

Тип

Описание

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

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

Ads

array of AdUpdateItem

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

Да

Структура AdUpdateItem

Id

long

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

Да

TextAd

TextAdUpdate

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

Либо TextAd, либо MobileAppAd, либо DynamicTextAd, либо TextImageAd, либо MobileAppImageAd, либо MobileAppCpcVideoAdBuilderAd, либо TextAdBuilderAd, либо MobileAppAdBuilderAd, либо CpcVideoAdBuilderAd, либо CpmBannerAdBuilderAd, либо CpmVideoAdBuilderAd, либо SmartAdBuilderAd.

TextImageAd

TextImageAdUpdate

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

TextAdBuilderAd

TextAdBuilderAdUpdate

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

CpmBannerAdBuilderAd

CpmBannerAdBuilderAdUpdate

Параметры медийного объявления.

CpmVideoAdBuilderAd

CpmVideoAdBuilderAdUpdate

Параметры медийного видеообъявления (в кампании с типом «Медийная кампания»).

ShoppingAd

ShoppingAdUpdate

Параметры товарного объявления.

ListingAd

ListingAdUpdate

Параметры объявления для страниц каталога.

Структура TextAdUpdate

Title

string

Заголовок 1.

Не более 56 символов c учетом «узких». Каждое слово не более 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

Идентификатор Турбо-страницы.

Внимание

Параметр устарел, переданное значение не будет сохранено.

Нет

BusinessId

long, nillable

Идентификатор профиля организации на Яндексе.

Получить данные профилей организаций можно с помощью метода Businesses.get.

Профиль организации можно привязать к объявлению, только если для него в параметре IsPublished возвращается значение YES.

Примечание

Профиль организации доступен по ссылке https://yandex.ru/profile/<id_профиля>

Нет

PreferVCardOverBusiness

YesNoEnum

Признак, который определяет приоритетность источника данных при показе объявления: YES — визитка, NO — профиль организации.

Внимание

Параметр устарел, вне зависимости от переданного значения, будет использовано значение NO.

Нет

ErirAdDescription

string

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

Нет

Структура 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

Валюта, в которой указана цена.

Нет

Структура 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

Идентификатор Турбо-страницы.

Нет

ErirAdDescription

string

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

Нет

Структура TextAdBuilderAdUpdate

Creative

AdBuilderAdUpdateItem

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

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

Нет

Href

string, nillable

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

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

Нет

TurboPageId

long, nillable

Идентификатор Турбо-страницы.

Нет

ErirAdDescription

string

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

Нет

Структура CpmBannerAdBuilderAdUpdate

Creative

AdBuilderAdUpdateItem

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

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

Нет

Href

string, nillable

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

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

Нет

TrackingPixels

ArrayOfString, nillable

Может содержать не более двух строк:

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

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

Нет

TurboPageId

long, nillable

Идентификатор Турбо-страницы.

Нет

ErirAdDescription

string

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

Нет

Структура CpmVideoAdBuilderAdUpdate

Creative

AdBuilderAdUpdateItem

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

См. раздел Видеореклама / Как запустить кампанию помощи Директа.

Нет

Href

string, nillable

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

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

Нет

TurboPageId

long, nillable

Идентификатор Турбо-страницы.

Нет

TrackingPixels

ArrayOfString, nillable

Счетчик показов ADFOX. В счетчике показов обязательно должен быть макрос %random% или %aw_random%. Не более 1024 символов.

Нет

ErirAdDescription

string

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

Нет

Структура AdBuilderAdUpdateItem

CreativeId

long

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

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

Да

Структура ShoppingAdUpdate

SitelinkSetId

long

Идентификатор набора быстрых ссылок.

Нет

CalloutSetting

CalloutSetting

CalloutSetting

Нет

BusinessId

long

Идентификатор профиля организации на Яндексе.

Получить данные профилей организаций можно с помощью метода Businesses.get.

Профиль организации можно привязать к объявлению, только если для него в параметре IsPublished возвращается значение YES.

Примечание

Профиль организации доступен по ссылке https://yandex.ru/profile/<id_профиля>

Нет

FeedFilterConditions

FeedFilterConditionsItem

Правила отбора товарных предложений. Не более 30 фильтров в массиве. Суммарная длина правил отбора — не более 65 кБайт (в формате JSON).

Товарное предложение отбирается для формирования объявлений, если оно удовлетворяет одновременно всем правилам отбора. Если параметр не задан, для формирования объявлений используются все товарные предложения из фида.

Нет

TitleSources

array of string

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

Нет

TextSources

array of string

Названия полей фида, которые используются для формирования текстов объявлений. Допустимые названия полей можно получить в методе feeds.get в поле TitleAndTextSources.

Нет

DefaultTexts

array of string

Тексты по умолчанию. Можно указать только одно значение.

Да

Структура ListingAdUpdate

SitelinkSetId

long

Идентификатор набора быстрых ссылок.

Нет

CalloutSetting

CalloutSetting

CalloutSetting

Нет

BusinessId

long

Идентификатор профиля организации на Яндексе.

Получить данные профилей организаций можно с помощью метода Businesses.get.

Профиль организации можно привязать к объявлению, только если для него в параметре IsPublished возвращается значение YES.

Примечание

Профиль организации доступен по ссылке https://yandex.ru/profile/<id_профиля>

Нет

FeedFilterConditions

FeedFilterConditionsItem

Правила отбора товарных предложений. Не более 30 фильтров в массиве. Суммарная длина правил отбора — не более 65 кБайт (в формате JSON).

Товарное предложение отбирается для формирования объявлений, если оно удовлетворяет одновременно всем правилам отбора. Если параметр не задан, для формирования объявлений используются все товарные предложения из фида.

Нет

TitleSources

array of string

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

Нет

TextSources

array of string

Названия полей фида, которые используются для формирования текстов объявлений. Допустимые названия полей можно получить в методе feeds.get в поле TitleAndTextSources.

Нет

DefaultTexts

array of string

Тексты по умолчанию. Можно указать только одно значение.

Да

Структура CalloutSetting

AdExtensions

AdExtensions

Расширения для объявления.

Да

Структура AdExtensions

AdExtensionId

long

Идентификатор расширения.

Да

Operation

string

Операция.
Возможные значения:

  • ADD;
  • REMOVE;
  • SET.

Да

Структура FeedFilterConditionsItem

Operand

string

Параметр фида.

Описание полей для каждого типа фида см. в разделе Настройка фильтров помощи Директа.

Да

Operator

StringConditionOperatorEnum

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

Да

Arguments

array of string

Массив строк, с которыми сравнивается операнд.

Да

Ответ

Структура ответа в формате 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"
              }]
            }
          }
        }]
      }
    }
Предыдущая
unarchive
Следующая
AdVideos: операции с видео