Документация
API версии 5. Руководство разработчика
API версии 5. Справочник

setAuto

Конструктор ставок — рассчитывает ставки для фраз по заданному алгоритму.
Метод выполняет назначение ставок в асинхронном режиме и не возвращает ставки. Получить ставки можно методом get
[no-highlight[

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

Подробнее get

]no-highlight]
.

Ставку можно назначить, только если в кампании выбрана ручная стратегия.

В случае если элемент входного массива содержит ставки, не соответствующие стратегии, то эти ставки применены не будут.

  • Если в кампании автоматическая стратегия, возвращается ошибка.
  • Если в кампании отключены показы на поиске, а в параметре Scope передано только значение SEARCH, то возвращается ошибка. Если переданы оба значения — SEARCH и NETWORK, то будут обновлены ставки только в сетях и выдано предупреждение.
  • Если в кампании ручная стратегия на поиске, при этом не предусмотрено независимое управление ставками в сетях или показы в сетях отключены, а в параметре Scope передано только значение NETWORK, то возвращается ошибка. Если переданы оба значения — SEARCH и NETWORK, то будут обновлены ставки только на поиске и выдано предупреждение.
Внимание! 
  • Ставки и цены передаются через API Директа в виде целых чисел. Передаваемое значение представляет собой ставку или цену, умноженную на 1 000 000.

  • Все ставки и цены указываются в валюте рекламодателя.

Чтобы назначить ставки на поиске, передайте в параметре Scope
[no-highlight[

Указывает, какие ставки назначить. Массив может содержать следующие элементы (один или оба):

  • SEARCH — назначить ставки на поиске (Bid). Для расчета ставок используются значения, переданные в параметрах Position, IncreasePercent, CalculateBy, MaxBid.
  • NETWORK — назначить ставки в сетях (ContextBid). Для расчета ставок используются значения, переданные в параметрах ContextCoverage, IncreasePercent, MaxBid.

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

Да

]no-highlight]
значение SEARCH.
Для расчета ставки используются значения, переданные в параметрах Position
[no-highlight[

Позиция показа, ставка за которую используется как основа для расчета ставок на поиске.

К цене указанной позиции прибавляется надбавка (см. параметры IncreasePercent и CalculateBy).

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

Если в массиве Scope присутствует значение Search

]no-highlight]
, IncreasePercent
[no-highlight[

Процент надбавки от 0 до 1000. Если не задан, надбавка не рассчитывается.

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

Нет

]no-highlight]
, CalculateBy
[no-highlight[

База, на основе которой рассчитывается надбавка:

  • VALUE — цена позиции, указанной в Position.

  • DIFF — разница между минимальной ставкой за позицию, указанную в параметре Position, и за следующую позицию.

    При выборе позиции PREMIUMFIRST (P11) следующая позиция отсутствует и надбавка равна нулю. Это же верно при выборе позиции FOOTERFIRST (P21), если стоимость следующей позиции PREMIUMBLOCK (P14) меньше (редкая, но возможная ситуация).

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

Если в массиве Scope присутствует значение Search и задан параметр IncreasePercent

]no-highlight]
, MaxBid
[no-highlight[

Ограничение на ставку, умноженное на 1 000 000. Целое число.

Указывается в валюте рекламодателя. Ограничения приведены на странице Минимальный и максимальный размер цены за клик.

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

Нет

]no-highlight]
.
PositionCalculateByФормула расчета ставки
FOOTERBLOCKVALUE

Минимальная ставка за 4-ю позицию в гарантии + минимальная ставка за 4-ю позицию в гарантии × IncreasePercent / 100,

но не более MaxBid

DIFF

Минимальная ставка за 4-ю позицию в гарантии + (минимальная ставка за 1-ю позицию – минимальная ставка за 4-ю позицию в гарантии) × IncreasePercent / 100,

но не более MaxBid

FOOTERFIRSTVALUE

Минимальная ставка за 1-ю позицию в гарантии + минимальная ставка за 1-ю позицию в гарантии × IncreasePercent / 100,

но не более MaxBid

DIFF

Минимальная ставка за 1-ю позицию в гарантии + (минимальная ставка за 3-ю позицию в спецразмещении – минимальная ставка за 1-ю позицию в гарантии) × IncreasePercent / 100,

но не более MaxBid

PREMIUMBLOCK или P14VALUE

Минимальная ставка за 4-ю позицию в спецразмещении + минимальная ставка за 4-ю позицию в спецразмещении × IncreasePercent / 100,

но не более MaxBid

DIFF

Минимальная ставка за 4-ю позицию в спецразмещении + (минимальная ставка за 3-ю позицию в спецразмещении – минимальная ставка за 4-ю позицию в спецразмещении) × IncreasePercent / 100,

но не более MaxBid

P13VALUE

Минимальная ставка за 3-ю позицию в спецразмещении + минимальная ставка за 3-ю позицию в спецразмещении × IncreasePercent / 100,

но не более MaxBid

DIFF

Минимальная ставка за 3-ю позицию в спецразмещении + (минимальная ставка за 2-ю позицию в спецразмещении – минимальная ставка за 3-ю позицию в спецразмещении) × IncreasePercent / 100,

но не более MaxBid

P12VALUE

Минимальная ставка за 2-ю позицию в спецразмещении + минимальная ставка за 2-ю позицию в спецразмещении × IncreasePercent / 100,

но не более MaxBid

DIFF

Минимальная ставка за 2-ю позицию в спецразмещении + (минимальная ставка за 1-ю позицию в спецразмещении – минимальная ставка за 2-ю позицию в спецразмещении) × IncreasePercent / 100,

но не более MaxBid

PREMIUMFIRST или P11VALUE

Минимальная ставка за 1-ю позицию в спецразмещении + минимальная ставка за 1-ю позицию в спецразмещении × IncreasePercent / 100,

но не более MaxBid

DIFF

Минимальная ставка за 1-ю позицию в спецразмещении, но не более MaxBid

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

Ставку в сетях можно назначить только для стратегии, предусматривающей раздельное управление ставками на поиске и в сетях.

Чтобы назначить ставки в сетях, передайте в параметре Scope
[no-highlight[

Указывает, какие ставки назначить. Массив может содержать следующие элементы (один или оба):

  • SEARCH — назначить ставки на поиске (Bid). Для расчета ставок используются значения, переданные в параметрах Position, IncreasePercent, CalculateBy, MaxBid.
  • NETWORK — назначить ставки в сетях (ContextBid). Для расчета ставок используются значения, переданные в параметрах ContextCoverage, IncreasePercent, MaxBid.

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

Да

]no-highlight]
значение NETWORK.
Для расчета ставки используются значения, переданные в параметрах ContextCoverage
[no-highlight[

Частота показа (доля аудитории) в сетях. Указывается в процентах от 1 до 100.

К ставке, необходимой для охвата выбранной доли аудитории, прибавляется надбавка (см. параметр IncreasePercent).

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

Если в массиве Scope присутствует значение Network

]no-highlight]
, IncreasePercent
[no-highlight[

Процент надбавки от 0 до 1000. Если не задан, надбавка не рассчитывается.

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

Нет

]no-highlight]
, MaxBid
[no-highlight[

Ограничение на ставку, умноженное на 1 000 000. Целое число.

Указывается в валюте рекламодателя. Ограничения приведены на странице Минимальный и максимальный размер цены за клик.

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

Нет

]no-highlight]
.

Формула расчета ставки:

Ставка, при которой прогнозируется указанная частота показа + ставка, при которой прогнозируется указанная частота показа × IncreasePercent / 100,

но не более MaxBid.

Примечание. Расчет ставок носит вероятностный характер и не гарантирует охвата требуемой доли аудитории.

Ограничения

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

Количество объектов в одном вызове метода:

  • кампаний — не более 10;
  • групп — не более 1000;
  • фраз — не более 10 000.

Запрос

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

{
  "method": "setAuto",
  "params": { 
    "Bids
[no-highlight[

Параметры расчета ставок.

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

Да

]no-highlight]
": [{ /* BidSetAutoItem */ "CampaignId
[no-highlight[

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

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

Либо CampaignId, либо AdGroupId, либо KeywordId

]no-highlight]
": (long), "AdGroupId
[no-highlight[

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

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

Либо CampaignId, либо AdGroupId, либо KeywordId

]no-highlight]
": (long), "KeywordId
[no-highlight[

Идентификатор фразы. Указывается, если требуется обновить ставку для отдельной фразы.

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

Либо CampaignId, либо AdGroupId, либо KeywordId

]no-highlight]
": (long), "MaxBid
[no-highlight[

Ограничение на ставку, умноженное на 1 000 000. Целое число.

Указывается в валюте рекламодателя. Ограничения приведены на странице Минимальный и максимальный размер цены за клик.

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

Нет

]no-highlight]
": (long), "Position
[no-highlight[

Позиция показа, ставка за которую используется как основа для расчета ставок на поиске.

К цене указанной позиции прибавляется надбавка (см. параметры IncreasePercent и CalculateBy).

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

Если в массиве Scope присутствует значение Search

]no-highlight]
": ( "PREMIUMFIRST" | "PREMIUMBLOCK" | "FOOTERFIRST" | "FOOTERBLOCK" | "P11" | "P12" | "P13" | "P14" ), "IncreasePercent
[no-highlight[

Процент надбавки от 0 до 1000. Если не задан, надбавка не рассчитывается.

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

Нет

]no-highlight]
": (int), "CalculateBy
[no-highlight[

База, на основе которой рассчитывается надбавка:

  • VALUE — цена позиции, указанной в Position.

  • DIFF — разница между минимальной ставкой за позицию, указанную в параметре Position, и за следующую позицию.

    При выборе позиции PREMIUMFIRST (P11) следующая позиция отсутствует и надбавка равна нулю. Это же верно при выборе позиции FOOTERFIRST (P21), если стоимость следующей позиции PREMIUMBLOCK (P14) меньше (редкая, но возможная ситуация).

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

Если в массиве Scope присутствует значение Search и задан параметр IncreasePercent

]no-highlight]
": ( "VALUE" | "DIFF" ), "ContextCoverage
[no-highlight[

Частота показа (доля аудитории) в сетях. Указывается в процентах от 1 до 100.

К ставке, необходимой для охвата выбранной доли аудитории, прибавляется надбавка (см. параметр IncreasePercent).

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

Если в массиве Scope присутствует значение Network

]no-highlight]
": (int), "Scope
[no-highlight[

Указывает, какие ставки назначить. Массив может содержать следующие элементы (один или оба):

  • SEARCH — назначить ставки на поиске (Bid). Для расчета ставок используются значения, переданные в параметрах Position, IncreasePercent, CalculateBy, MaxBid.
  • NETWORK — назначить ставки в сетях (ContextBid). Для расчета ставок используются значения, переданные в параметрах ContextCoverage, IncreasePercent, MaxBid.

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

Да

]no-highlight]
": [( "SEARCH" | "NETWORK" ), ... ] /* required */ }, ... ] /* required */ } }
Параметр Тип Описание Обязательный
Структура params (для JSON) / SetAutoRequest (для SOAP)
Bids array of BidSetAutoItemПараметры расчета ставок.Да
Структура BidSetAutoItem
CampaignId longИдентификатор кампании. Указывается, если требуется обновить ставки для всех фраз кампании.Либо CampaignId, либо AdGroupId, либо KeywordId
AdGroupId longИдентификатор группы объявлений. Указывается, если требуется обновить ставки для всех фраз группы.
KeywordId longИдентификатор фразы. Указывается, если требуется обновить ставку для отдельной фразы.
Scope array of ScopeEnumУказывает, какие ставки назначить. Массив может содержать следующие элементы (один или оба):
  • SEARCH — назначить ставки на поиске (Bid). Для расчета ставок используются значения, переданные в параметрах Position
    [no-highlight[

    Позиция показа, ставка за которую используется как основа для расчета ставок на поиске.

    К цене указанной позиции прибавляется надбавка (см. параметры IncreasePercent и CalculateBy).

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

    Если в массиве Scope присутствует значение Search

    ]no-highlight]
    , IncreasePercent
    [no-highlight[

    Процент надбавки от 0 до 1000. Если не задан, надбавка не рассчитывается.

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

    Нет

    ]no-highlight]
    , CalculateBy
    [no-highlight[

    База, на основе которой рассчитывается надбавка:

    • VALUE — цена позиции, указанной в Position.

    • DIFF — разница между минимальной ставкой за позицию, указанную в параметре Position, и за следующую позицию.

      При выборе позиции PREMIUMFIRST (P11) следующая позиция отсутствует и надбавка равна нулю. Это же верно при выборе позиции FOOTERFIRST (P21), если стоимость следующей позиции PREMIUMBLOCK (P14) меньше (редкая, но возможная ситуация).

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

    Если в массиве Scope присутствует значение Search и задан параметр IncreasePercent

    ]no-highlight]
    , MaxBid
    [no-highlight[

    Ограничение на ставку, умноженное на 1 000 000. Целое число.

    Указывается в валюте рекламодателя. Ограничения приведены на странице Минимальный и максимальный размер цены за клик.

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

    Нет

    ]no-highlight]
    .
  • NETWORK — назначить ставки в сетях (ContextBid). Для расчета ставок используются значения, переданные в параметрах ContextCoverage
    [no-highlight[

    Частота показа (доля аудитории) в сетях. Указывается в процентах от 1 до 100.

    К ставке, необходимой для охвата выбранной доли аудитории, прибавляется надбавка (см. параметр IncreasePercent).

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

    Если в массиве Scope присутствует значение Network

    ]no-highlight]
    , IncreasePercent
    [no-highlight[

    Процент надбавки от 0 до 1000. Если не задан, надбавка не рассчитывается.

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

    Нет

    ]no-highlight]
    , MaxBid
    [no-highlight[

    Ограничение на ставку, умноженное на 1 000 000. Целое число.

    Указывается в валюте рекламодателя. Ограничения приведены на странице Минимальный и максимальный размер цены за клик.

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

    Нет

    ]no-highlight]
    .
Да
MaxBid long

Ограничение на ставку, умноженное на 1 000 000. Целое число.

Указывается в валюте рекламодателя. Ограничения приведены на странице Минимальный и максимальный размер цены за клик.

Нет
Position PositionEnum

Позиция показа, ставка за которую используется как основа для расчета ставок на поиске.

К цене указанной позиции прибавляется надбавка (см. параметры IncreasePercent и CalculateBy).

Если в массиве Scope присутствует значение Search
IncreasePercent intПроцент надбавки от 0 до 1000. Если не задан, надбавка не рассчитывается.Нет
CalculateBy CalculateByEnum

База, на основе которой рассчитывается надбавка:

  • VALUE — цена позиции, указанной в Position.

  • DIFF — разница между минимальной ставкой за позицию, указанную в параметре Position, и за следующую позицию.

    При выборе позиции PREMIUMFIRST (P11) следующая позиция отсутствует и надбавка равна нулю. Это же верно при выборе позиции FOOTERFIRST (P21), если стоимость следующей позиции PREMIUMBLOCK (P14) меньше (редкая, но возможная ситуация).

Если в массиве Scope присутствует значение Search и задан параметр IncreasePercent
ContextCoverage int

Частота показа (доля аудитории) в сетях. Указывается в процентах от 1 до 100.

К ставке, необходимой для охвата выбранной доли аудитории, прибавляется надбавка (см. параметр IncreasePercent).

Если в массиве Scope присутствует значение Network
Внимание! Параметры CampaignId, AdGroupId и KeywordId являются взаимоисключающими. В одном запросе можно указывать только один из этих параметров.

Ответ

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

{
  "result": { 
    "SetAutoResults
[no-highlight[

Результаты назначения ставок и/или приоритетов.

]no-highlight]
": [{ /* BidActionResult */ "Warnings
[no-highlight[

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

]no-highlight]
": [{ /* ExceptionNotification */ "Code": (int), /* required */ "Message": (string), /* required */ "Details": (string) }, ... ], "Errors
[no-highlight[

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

]no-highlight]
": [{ /* ExceptionNotification */ "Code": (int), /* required */ "Message": (string), /* required */ "Details": (string) }, ... ], "CampaignId
[no-highlight[

Идентификатор кампании. Возвращается в случае отсутствия ошибок, см. раздел Операции над массивом объектов (если был указан в запросе).

]no-highlight]
": (long), "AdGroupId
[no-highlight[

Идентификатор группы объявлений. Возвращается в случае отсутствия ошибок, см. раздел Операции над массивом объектов (если был указан в запросе).

]no-highlight]
": (long), "KeywordId
[no-highlight[

Идентификатор фразы. Возвращается в случае отсутствия ошибок, см. раздел Операции над массивом объектов (если был указан в запросе).

]no-highlight]
": (long) }, ... ] } }
Параметр Тип Описание
Структура result (для JSON) / SetAutoResponse (для SOAP)
SetAutoResults array of BidActionResultРезультаты назначения ставок и/или приоритетов.
Структура BidActionResult
CampaignId longИдентификатор кампании. Возвращается в случае отсутствия ошибок, см. раздел Операции над массивом объектов (если был указан в запросе).
AdGroupId longИдентификатор группы объявлений. Возвращается в случае отсутствия ошибок, см. раздел Операции над массивом объектов (если был указан в запросе).
KeywordId longИдентификатор фразы. Возвращается в случае отсутствия ошибок, см. раздел Операции над массивом объектов (если был указан в запросе).
Warnings array of ExceptionNotification

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

Errors array of ExceptionNotification

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

Примеры

Пример запроса

Назначить на поиске цену 1-го места в гарантии + 50% от разницы до спецразмещения, но не более 0,25.

{
  "method" : "setAuto",
  "params" : {
    "Bids" : [
      {
        "Scope" : [
          "SEARCH"
        ],
        "IncreasePercent" : 50,
        "CalculateBy" : "DIFF",
        "Position" : "FOOTERFIRST",
        "KeywordId" : 1574449505,
        "MaxBid" : 250000
      }
    ]
  }
}
Пример ответа
{
  "result" : {
    "SetAutoResults" : [
      {
        "KeywordId" : 1574449505
      }
    ]
  }
}