update

Изменяет параметры кампаний.

  1. Ограничения
  2. Запрос
  3. Ответ
Внимание. Все денежные параметры кампаний (дневной бюджет, недельный бюджет, средняя цена для автоматических стратегий) передаются через API Директа в виде целых чисел. Передаваемое значение представляет собой денежное значение в валюте рекламодателя, умноженное на 1 000 000.

Ограничения

Не более 10 кампаний в одном вызове метода.

Не более 3 изменений суммы дневного бюджета в сутки для одной кампании.

Запрос

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

{
  "method": "update",
  "params": { /* params */
    "Campaigns": [{  /* CampaignUpdateItem */
      "Id": (long), /* required */
      "Name": (string),
      "StartDate": (string),
      "DailyBudget": {  /* DailyBudget */
        "Amount": (long), /* required */
        "Mode": ( "STANDARD" | "DISTRIBUTED" ) /* required */
      }, /* nillable */
      "EndDate": (string), /* nillable */
      "NegativeKeywords": {  /* ArrayOfString */
        "Items": [(string), ... ] /* required */
      }, /* nillable */
      "BlockedIps": {  /* ArrayOfString */
        "Items": [(string), ... ] /* required */
      }, /* nillable */
      "ExcludedSites": {  /* ArrayOfString */
        "Items": [(string), ... ] /* required */
      }, /* nillable */
      "TextCampaign": {  /* TextCampaignUpdateItem */
        ... text campaign params ...
      },
      "MobileAppCampaign": {  /* MobileAppCampaignUpdateItem */
        ... mobile app campaign params ...
      },
      "DynamicTextCampaign": {  /* DynamicTextCampaignUpdateItem */
        ... dynamic text campaign params ...
      },
      "CpmBannerCampaign": {  /* CpmBannerCampaignUpdateItem */
        ... cpm banner campaign params ...
      },
      "SmartCampaign": {  /* SmartCampaignUpdateItem */
        ... smart campaign params ...
      },
      "UnifiedCampaign": {  /* SmartCampaignUpdateItem */
        ... unified campaign params ...
      },
      "ClientInfo": (string),
      "Notification": {  /* Notification */
        "SmsSettings": {  /* SmsSettings */
          "Events": [( "MONITORING" | ... | "FINISHED" ), ... ],
          "TimeFrom": (string),
          "TimeTo": (string)
        },
        "EmailSettings": {  /* EmailSettings */
          "Email": (string),
          "CheckPositionInterval": (int),
          "WarningBalance": (int),
          "SendAccountNews": ( "YES" | "NO" ),
          "SendWarnings": ( "YES" | "NO" )
        }
      },
      "TimeTargeting": {  /* TimeTargeting */
        "Schedule": {  /* ArrayOfString */
          "Items": [(string), ... ] /* required */
        },
        "ConsiderWorkingWeekends": ( "YES" | "NO" ), /* required */
        "HolidaysSchedule": {  /* TimeTargetingOnPublicHolidays */
          "SuspendOnHolidays": ( "YES" | "NO" ), /* required */
          "BidPercent": (int),
          "StartHour": (int),
          "EndHour": (int)
        }  /* nillable */
      },
      "TimeZone": (string)
    }, ... ] /* required */
  }
}
Параметр Тип Описание Обязательный
Структура params (для JSON) / AddRequest (для SOAP)
Campaigns array of CampaignUpdateItem

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

Да
Структура CampaignUpdateItem
Id long Идентификатор кампании, параметры которой требуется изменить. Да
Name string Название кампании (до 255 символов). Нет
ClientInfo string Название клиента (до 255 символов). Значение по умолчанию — наименование из настроек рекламодателя. Нельзя задать для UnifiedCampaign. Нет
StartDate string

Дата начала показов объявлений в формате YYYY-MM-DD. Должна быть не меньше текущей даты.

Показы объявлений начинаются в 00:00 по московскому времени (независимо от значения параметра TimeZone). На время начала показов влияют настройки временного таргетинга (параметр TimeTargeting).

Показы объявлений возможны при условии, что хотя бы одно объявление принято модерацией и внесены средства на кампанию или на общий счет.

Если для кампании установлен бюджет на период, значение этого поля игнорируется, приоритет – у периода стратегии.

Нет
EndDate string, nillable Дата окончания показов объявлений в формате YYYY-MM-DD. Показы объявлений прекращаются в 24:00 по московскому времени (независимо от значения параметра TimeZone). Нет
TimeTargeting TimeTargeting Настройки временного таргетинга и почасовой корректировки ставок. Указываются по времени часового пояса, указанного в параметре TimeZone. Нет
TimeZone string

Часовой пояс в месте нахождения рекламодателя. Справочник часовых поясов можно получить с помощью метода Dictionaries.get.

Значение по умолчанию Europe/Moscow.

Нет
NegativeKeywords ArrayOfString, nillable

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

Ограничение. Для кампаний с типом «Медийная кампания» параметр не поддерживается.

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

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

Нет
BlockedIps ArrayOfString, nillable Массив IP-адресов, которым не нужно показывать объявления. Не более 25 элементов в массиве. Нет
ExcludedSites ArrayOfString, nillable

Массив мест показа, где не нужно показывать объявления:

  • доменные имена сайтов;

  • идентификаторы мобильных приложений (bundle ID для iOS, package name для Android);

  • наименования внешних сетей (SSP). Список наименований можно получить с помощью метода Dictionaries.get.

Не более 1000 элементов в массиве. Не более 255 символов в каждом элементе массива.

Нет
DailyBudget DailyBudget, nillable

Настройки дневного бюджета кампании.

Управление дневным бюджетом доступно, если в кампании выбрана ручная стратегия показа. В противном случае при попытке задать дневной бюджет возвращается ошибка.

Чтобы сбросить дневной бюджет, передайте null (nil).

Нет
Notification Notification Настройки SMS- и email-уведомлений. Нельзя задать для UnifiedCampaign. Нет
TextCampaign TextCampaignUpdateItem Настройки для кампании с типом «Текстово-графические объявления». Описание структуры данных см. в разделе update: параметры TextCampaign. Нет
MobileAppCampaign MobileAppCampaignUpdateItem Настройки для кампании с типом «Реклама мобильных приложений». Описание структуры данных см. в разделе update: параметры MobileAppCampaign. Нет
DynamicTextCampaign DynamicTextCampaignUpdateItem Настройки для кампании с типом «Динамические объявления». Описание структуры данных см. в разделе update: параметры DynamicTextCampaign. Нет
CpmBannerCampaign CpmBannerCampaignUpdateItem Настройки для кампании с типом «Медийная кампания». Описание структуры данных см. в разделе update: параметры CpmBannerCampaign. Нет
SmartCampaign SmartCampaignUpdateItem Настройки для кампании с типом «Смарт-баннеры». Описание структуры данных см. в разделе update: параметры SmartCampaign. Нет
UnifiedCampaign UnifiedCampaignUpdateItem Настройки для кампании с типом «Единая перфоманс кампания». Описание структуры данных см. в разделе update: параметры UnifiedCampaign. Нет
Структура TimeTargeting
Schedule ArrayOfString

Настройки временного таргетинга и почасовой корректировки ставок. Не более 7 элементов в массиве.

Каждый элемент массива содержит 25 чисел, разделенных запятыми. Первое число — номер дня недели: от 1 (понедельник) до 7 (воскресенье). Следующие 24 числа — последовательность коэффициентов к ставке для показа объявлений в соответствующие часы. Коэффициенты указываются в процентах от 0 до 200, значение должно быть кратно 10. Коэффициент 0 означает, что объявления в этот час не показываются. Пример элемента массива: 1, 0, 0, 50, 50, 100, 100, 150, 200, 200, 150, 100, 100, 80, 70, 100, 100, 100, 50, 50, 40, 30, 0, 0, 0

Примечание.
  • Если в массиве не указан элемент, соответствующий дню недели, то для этого дня все коэффициенты устанавливаются равными 100.
  • Если выбрана автоматическая стратегия показа, коэффициент 0 означает запрет показов, а любой другой коэффициент означает разрешение показов (то есть эквивалентен 100).
Нет
ConsiderWorkingWeekends YesNoEnum

Менять ли расписание показов при переносе рабочего дня на субботу или воскресенье.

Например, если рабочий день перенесен с понедельника на субботу, при значении YES в рабочую субботу пойдут показы по расписанию понедельника, а в нерабочий понедельник, — по расписанию субботы.

Да
HolidaysSchedule TimeTargetingOnPublicHolidays, nillable

Настройки показа в праздничные дни.

Если часовой пояс, указанный в параметре TimeZone, относится к России, Украине, Беларуси, Казахстану или Турции, то используется календарь праздников и переносов рабочих дней соответствующей страны. В остальных случаях используется российский календарь.

Нет
Структура TimeTargetingOnPublicHolidays
SuspendOnHolidays YesNoEnum

Останавливать ли объявления в праздничные нерабочие дни: YES — останавливать, NO — не останавливать.

Примечание. Параметры BidPercent, StartHour и EndHour допускается задавать только при значении NO параметра SuspendOnHolidays.
Да
BidPercent int Коэффициент к ставке при показе в праздничные нерабочие дни. Указывается в процентах от 10 до 200, значение должно быть кратно 10. Нет
StartHour int Время (в часах) начала показов в праздничные нерабочие дни. От 0 до 23. При значении NO параметра SuspendOnHolidays
EndHour int Время (в часах) окончания показов в праздничные нерабочие дни. От 1 до 24. При значении NO параметра SuspendOnHolidays
Структура DailyBudget
Amount long

Дневной бюджет кампании в валюте рекламодателя, умноженный на 1 000 000.

Минимальный дневной бюджет для каждой валюты представлен в справочнике валют. Справочник валют можно получить с помощью метода Dictionaries.get.

Да
Mode DailyBudgetModeEnum

Режим показа объявлений:

  • STANDARD — стандартный.
  • DISTRIBUTED — распределенный.

См. подраздел Средний дневной бюджет раздела «Ручное управление ставками» помощи Директа.

Да
Структура Notification
SmsSettings SmsSettings

Настройки отправки SMS-уведомлений. Телефонный номер для отправки берется из профиля рекламодателя на Яндексе (см. раздел Мои телефоны помощи Яндекс Паспорта).

Нет
EmailSettings EmailSettings Настройки отправки уведомлений по электронной почте. Нет
Структура SmsSettings
Events array of SmsEventsEnum
События, о которых необходимо информировать по SMS:
  • MONITORING — остановка и возобновление показов объявлений мониторингом доступности сайта по данным Метрики;
  • MODERATION — объявления приняты или отклонены модерацией;
  • MONEY_IN — поступление средств на баланс кампании (не используется при подключенном общем счете);
  • MONEY_OUT — исчерпание средств на балансе кампании (не используется при подключенном общем счете);
  • FINISHED — окончание кампании.
Нет
TimeFrom string

Время, начиная с которого разрешено отправлять SMS о событиях, связанных с кампанией. Указывается в формате HH:MM, минуты задают кратно 15 (0, 15, 30, 45). Например, 19:45.

Нет
TimeTo string

Время, до которого разрешено отправлять SMS о событиях, связанных с кампанией. Указывается в формате HH:MM, минуты задают кратно 15 (0, 15, 30, 45). Например, 19:45.

Нет
Структура EmailSettings
Email string

Адрес электронной почты для отправки уведомлений о событиях, связанных с кампанией.

Значение по умолчанию — адрес рекламодателя.

Нет
CheckPositionInterval int

Периодичность проверки прогноза трафика — 15, 30 или 60 минут. Значение по умолчанию — 60.

Уведомление отправляется, если прогноз трафика стал ниже того, который обеспечивала ставка на момент установки.

Нет
WarningBalance int

Минимальный баланс, при уменьшении до которого отправляется уведомление. Задается в процентах от суммы последнего платежа, от 1 до 50. Значение по умолчанию — 20.

Если у клиента подключен общий счет, параметр не используется.

Нет
SendAccountNews YesNoEnum

Отправлять ли уведомления о событиях, связанных с кампанией. Задается для кампаний, обслуживаемых персональным менеджером в Яндексе. Для кампаний, не обслуживаемых персональным менеджером, переданное значение игнорируется. Значение по умолчанию — NO.

Нет
SendWarnings YesNoEnum Отправлять ли уведомления по электронной почте. Значение по умолчанию — NO. Нет
Параметр Тип Описание Обязательный
Структура params (для JSON) / AddRequest (для SOAP)
Campaigns array of CampaignUpdateItem

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

Да
Структура CampaignUpdateItem
Id long Идентификатор кампании, параметры которой требуется изменить. Да
Name string Название кампании (до 255 символов). Нет
ClientInfo string Название клиента (до 255 символов). Значение по умолчанию — наименование из настроек рекламодателя. Нельзя задать для UnifiedCampaign. Нет
StartDate string

Дата начала показов объявлений в формате YYYY-MM-DD. Должна быть не меньше текущей даты.

Показы объявлений начинаются в 00:00 по московскому времени (независимо от значения параметра TimeZone). На время начала показов влияют настройки временного таргетинга (параметр TimeTargeting).

Показы объявлений возможны при условии, что хотя бы одно объявление принято модерацией и внесены средства на кампанию или на общий счет.

Если для кампании установлен бюджет на период, значение этого поля игнорируется, приоритет – у периода стратегии.

Нет
EndDate string, nillable Дата окончания показов объявлений в формате YYYY-MM-DD. Показы объявлений прекращаются в 24:00 по московскому времени (независимо от значения параметра TimeZone). Нет
TimeTargeting TimeTargeting Настройки временного таргетинга и почасовой корректировки ставок. Указываются по времени часового пояса, указанного в параметре TimeZone. Нет
TimeZone string

Часовой пояс в месте нахождения рекламодателя. Справочник часовых поясов можно получить с помощью метода Dictionaries.get.

Значение по умолчанию Europe/Moscow.

Нет
NegativeKeywords ArrayOfString, nillable

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

Ограничение. Для кампаний с типом «Медийная кампания» параметр не поддерживается.

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

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

Нет
BlockedIps ArrayOfString, nillable Массив IP-адресов, которым не нужно показывать объявления. Не более 25 элементов в массиве. Нет
ExcludedSites ArrayOfString, nillable

Массив мест показа, где не нужно показывать объявления:

  • доменные имена сайтов;

  • идентификаторы мобильных приложений (bundle ID для iOS, package name для Android);

  • наименования внешних сетей (SSP). Список наименований можно получить с помощью метода Dictionaries.get.

Не более 1000 элементов в массиве. Не более 255 символов в каждом элементе массива.

Нет
DailyBudget DailyBudget, nillable

Настройки дневного бюджета кампании.

Управление дневным бюджетом доступно, если в кампании выбрана ручная стратегия показа. В противном случае при попытке задать дневной бюджет возвращается ошибка.

Чтобы сбросить дневной бюджет, передайте null (nil).

Нет
Notification Notification Настройки SMS- и email-уведомлений. Нельзя задать для UnifiedCampaign. Нет
TextCampaign TextCampaignUpdateItem Настройки для кампании с типом «Текстово-графические объявления». Описание структуры данных см. в разделе update: параметры TextCampaign. Нет
MobileAppCampaign MobileAppCampaignUpdateItem Настройки для кампании с типом «Реклама мобильных приложений». Описание структуры данных см. в разделе update: параметры MobileAppCampaign. Нет
DynamicTextCampaign DynamicTextCampaignUpdateItem Настройки для кампании с типом «Динамические объявления». Описание структуры данных см. в разделе update: параметры DynamicTextCampaign. Нет
CpmBannerCampaign CpmBannerCampaignUpdateItem Настройки для кампании с типом «Медийная кампания». Описание структуры данных см. в разделе update: параметры CpmBannerCampaign. Нет
SmartCampaign SmartCampaignUpdateItem Настройки для кампании с типом «Смарт-баннеры». Описание структуры данных см. в разделе update: параметры SmartCampaign. Нет
UnifiedCampaign UnifiedCampaignUpdateItem Настройки для кампании с типом «Единая перфоманс кампания». Описание структуры данных см. в разделе update: параметры UnifiedCampaign. Нет
Структура TimeTargeting
Schedule ArrayOfString

Настройки временного таргетинга и почасовой корректировки ставок. Не более 7 элементов в массиве.

Каждый элемент массива содержит 25 чисел, разделенных запятыми. Первое число — номер дня недели: от 1 (понедельник) до 7 (воскресенье). Следующие 24 числа — последовательность коэффициентов к ставке для показа объявлений в соответствующие часы. Коэффициенты указываются в процентах от 0 до 200, значение должно быть кратно 10. Коэффициент 0 означает, что объявления в этот час не показываются. Пример элемента массива: 1, 0, 0, 50, 50, 100, 100, 150, 200, 200, 150, 100, 100, 80, 70, 100, 100, 100, 50, 50, 40, 30, 0, 0, 0

Примечание.
  • Если в массиве не указан элемент, соответствующий дню недели, то для этого дня все коэффициенты устанавливаются равными 100.
  • Если выбрана автоматическая стратегия показа, коэффициент 0 означает запрет показов, а любой другой коэффициент означает разрешение показов (то есть эквивалентен 100).
Нет
ConsiderWorkingWeekends YesNoEnum

Менять ли расписание показов при переносе рабочего дня на субботу или воскресенье.

Например, если рабочий день перенесен с понедельника на субботу, при значении YES в рабочую субботу пойдут показы по расписанию понедельника, а в нерабочий понедельник, — по расписанию субботы.

Да
HolidaysSchedule TimeTargetingOnPublicHolidays, nillable

Настройки показа в праздничные дни.

Если часовой пояс, указанный в параметре TimeZone, относится к России, Украине, Беларуси, Казахстану или Турции, то используется календарь праздников и переносов рабочих дней соответствующей страны. В остальных случаях используется российский календарь.

Нет
Структура TimeTargetingOnPublicHolidays
SuspendOnHolidays YesNoEnum

Останавливать ли объявления в праздничные нерабочие дни: YES — останавливать, NO — не останавливать.

Примечание. Параметры BidPercent, StartHour и EndHour допускается задавать только при значении NO параметра SuspendOnHolidays.
Да
BidPercent int Коэффициент к ставке при показе в праздничные нерабочие дни. Указывается в процентах от 10 до 200, значение должно быть кратно 10. Нет
StartHour int Время (в часах) начала показов в праздничные нерабочие дни. От 0 до 23. При значении NO параметра SuspendOnHolidays
EndHour int Время (в часах) окончания показов в праздничные нерабочие дни. От 1 до 24. При значении NO параметра SuspendOnHolidays
Структура DailyBudget
Amount long

Дневной бюджет кампании в валюте рекламодателя, умноженный на 1 000 000.

Минимальный дневной бюджет для каждой валюты представлен в справочнике валют. Справочник валют можно получить с помощью метода Dictionaries.get.

Да
Mode DailyBudgetModeEnum

Режим показа объявлений:

  • STANDARD — стандартный.
  • DISTRIBUTED — распределенный.

См. подраздел Средний дневной бюджет раздела «Ручное управление ставками» помощи Директа.

Да
Структура Notification
SmsSettings SmsSettings

Настройки отправки SMS-уведомлений. Телефонный номер для отправки берется из профиля рекламодателя на Яндексе (см. раздел Мои телефоны помощи Яндекс Паспорта).

Нет
EmailSettings EmailSettings Настройки отправки уведомлений по электронной почте. Нет
Структура SmsSettings
Events array of SmsEventsEnum
События, о которых необходимо информировать по SMS:
  • MONITORING — остановка и возобновление показов объявлений мониторингом доступности сайта по данным Метрики;
  • MODERATION — объявления приняты или отклонены модерацией;
  • MONEY_IN — поступление средств на баланс кампании (не используется при подключенном общем счете);
  • MONEY_OUT — исчерпание средств на балансе кампании (не используется при подключенном общем счете);
  • FINISHED — окончание кампании.
Нет
TimeFrom string

Время, начиная с которого разрешено отправлять SMS о событиях, связанных с кампанией. Указывается в формате HH:MM, минуты задают кратно 15 (0, 15, 30, 45). Например, 19:45.

Нет
TimeTo string

Время, до которого разрешено отправлять SMS о событиях, связанных с кампанией. Указывается в формате HH:MM, минуты задают кратно 15 (0, 15, 30, 45). Например, 19:45.

Нет
Структура EmailSettings
Email string

Адрес электронной почты для отправки уведомлений о событиях, связанных с кампанией.

Значение по умолчанию — адрес рекламодателя.

Нет
CheckPositionInterval int

Периодичность проверки прогноза трафика — 15, 30 или 60 минут. Значение по умолчанию — 60.

Уведомление отправляется, если прогноз трафика стал ниже того, который обеспечивала ставка на момент установки.

Нет
WarningBalance int

Минимальный баланс, при уменьшении до которого отправляется уведомление. Задается в процентах от суммы последнего платежа, от 1 до 50. Значение по умолчанию — 20.

Если у клиента подключен общий счет, параметр не используется.

Нет
SendAccountNews YesNoEnum

Отправлять ли уведомления о событиях, связанных с кампанией. Задается для кампаний, обслуживаемых персональным менеджером в Яндексе. Для кампаний, не обслуживаемых персональным менеджером, переданное значение игнорируется. Значение по умолчанию — NO.

Нет
SendWarnings YesNoEnum Отправлять ли уведомления по электронной почте. Значение по умолчанию — NO. Нет

Ответ

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

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