setAuto

API версии 5. Справочник

Bids: управление ставками

setAuto

Конструктор ставок — рассчитывает ставки для фраз по заданному алгоритму.

Метод выполняет назначение ставок в асинхронном режиме и не возвращает ставки. Получить ставки можно методом get.

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

Метод не сбрасывает значение автоматической ставки (AutotargetingSearchBidIsAuto).

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

Если в кампании автоматическая стратегия, возвращается ошибка.
Если в кампании отключены показы на поиске, а в параметре Scope передано только значение SEARCH, то возвращается ошибка. Если переданы оба значения — SEARCH и NETWORK, то будут обновлены ставки только в сетях и выдано предупреждение.
Если в кампании ручная стратегия на поиске, при этом не предусмотрено независимое управление ставками в сетях или показы в сетях отключены, а в параметре Scope передано только значение NETWORK, то возвращается ошибка. Если переданы оба значения — SEARCH и NETWORK, то будут обновлены ставки только на поиске и выдано предупреждение.

Внимание.

Ставки и цены передаются через API Директа в виде целых чисел. Передаваемое значение представляет собой ставку или цену, умноженную на 1 000 000.
Все ставки и цены указываются в валюте рекламодателя.

Чтобы назначить ставки на поиске, передайте в параметре Scope значение SEARCH.

Для расчета ставки используются значения, переданные в параметрах Position, IncreasePercent, CalculateBy, MaxBid.


Position	CalculateBy	Формула расчета ставки
FOOTERBLOCK	VALUE	Минимальная ставка за 4-ю позицию в гарантии + минимальная ставка за 4-ю позицию в гарантии × IncreasePercent / 100, но не более MaxBid
FOOTERBLOCK	DIFF	Минимальная ставка за 4-ю позицию в гарантии + (минимальная ставка за 1-ю позицию – минимальная ставка за 4-ю позицию в гарантии) × IncreasePercent / 100, но не более MaxBid
FOOTERFIRST	VALUE	Минимальная ставка за 1-ю позицию в гарантии + минимальная ставка за 1-ю позицию в гарантии × IncreasePercent / 100, но не более MaxBid
FOOTERFIRST	DIFF	Минимальная ставка за 1-ю позицию в гарантии + (минимальная ставка за 3-ю позицию в спецразмещении – минимальная ставка за 1-ю позицию в гарантии) × IncreasePercent / 100, но не более MaxBid
PREMIUMBLOCK или P14	VALUE	Минимальная ставка за 4-ю позицию в спецразмещении + минимальная ставка за 4-ю позицию в спецразмещении × IncreasePercent / 100, но не более MaxBid
PREMIUMBLOCK или P14	DIFF	Минимальная ставка за 4-ю позицию в спецразмещении + (минимальная ставка за 3-ю позицию в спецразмещении – минимальная ставка за 4-ю позицию в спецразмещении) × IncreasePercent / 100, но не более MaxBid
P13	VALUE	Минимальная ставка за 3-ю позицию в спецразмещении + минимальная ставка за 3-ю позицию в спецразмещении × IncreasePercent / 100, но не более MaxBid
P13	DIFF	Минимальная ставка за 3-ю позицию в спецразмещении + (минимальная ставка за 2-ю позицию в спецразмещении – минимальная ставка за 3-ю позицию в спецразмещении) × IncreasePercent / 100, но не более MaxBid
P12	VALUE	Минимальная ставка за 2-ю позицию в спецразмещении + минимальная ставка за 2-ю позицию в спецразмещении × IncreasePercent / 100, но не более MaxBid
P12	DIFF	Минимальная ставка за 2-ю позицию в спецразмещении + (минимальная ставка за 1-ю позицию в спецразмещении – минимальная ставка за 2-ю позицию в спецразмещении) × IncreasePercent / 100, но не более MaxBid
PREMIUMFIRST или P11	VALUE	Минимальная ставка за 1-ю позицию в спецразмещении + минимальная ставка за 1-ю позицию в спецразмещении × IncreasePercent / 100, но не более MaxBid
PREMIUMFIRST или P11	DIFF	Минимальная ставка за 1-ю позицию в спецразмещении, но не более MaxBid


Position	CalculateBy	Формула расчета ставки
FOOTERBLOCK	VALUE	Минимальная ставка за 4-ю позицию в гарантии + минимальная ставка за 4-ю позицию в гарантии × IncreasePercent / 100, но не более MaxBid
FOOTERBLOCK	DIFF	Минимальная ставка за 4-ю позицию в гарантии + (минимальная ставка за 1-ю позицию – минимальная ставка за 4-ю позицию в гарантии) × IncreasePercent / 100, но не более MaxBid
FOOTERFIRST	VALUE	Минимальная ставка за 1-ю позицию в гарантии + минимальная ставка за 1-ю позицию в гарантии × IncreasePercent / 100, но не более MaxBid
FOOTERFIRST	DIFF	Минимальная ставка за 1-ю позицию в гарантии + (минимальная ставка за 3-ю позицию в спецразмещении – минимальная ставка за 1-ю позицию в гарантии) × IncreasePercent / 100, но не более MaxBid
PREMIUMBLOCK или P14	VALUE	Минимальная ставка за 4-ю позицию в спецразмещении + минимальная ставка за 4-ю позицию в спецразмещении × IncreasePercent / 100, но не более MaxBid
PREMIUMBLOCK или P14	DIFF	Минимальная ставка за 4-ю позицию в спецразмещении + (минимальная ставка за 3-ю позицию в спецразмещении – минимальная ставка за 4-ю позицию в спецразмещении) × IncreasePercent / 100, но не более MaxBid
P13	VALUE	Минимальная ставка за 3-ю позицию в спецразмещении + минимальная ставка за 3-ю позицию в спецразмещении × IncreasePercent / 100, но не более MaxBid
P13	DIFF	Минимальная ставка за 3-ю позицию в спецразмещении + (минимальная ставка за 2-ю позицию в спецразмещении – минимальная ставка за 3-ю позицию в спецразмещении) × IncreasePercent / 100, но не более MaxBid
P12	VALUE	Минимальная ставка за 2-ю позицию в спецразмещении + минимальная ставка за 2-ю позицию в спецразмещении × IncreasePercent / 100, но не более MaxBid
P12	DIFF	Минимальная ставка за 2-ю позицию в спецразмещении + (минимальная ставка за 1-ю позицию в спецразмещении – минимальная ставка за 2-ю позицию в спецразмещении) × IncreasePercent / 100, но не более MaxBid
PREMIUMFIRST или P11	VALUE	Минимальная ставка за 1-ю позицию в спецразмещении + минимальная ставка за 1-ю позицию в спецразмещении × IncreasePercent / 100, но не более MaxBid
PREMIUMFIRST или P11	DIFF	Минимальная ставка за 1-ю позицию в спецразмещении, но не более MaxBid

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

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

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

Для расчета ставки используются значения, переданные в параметрах ContextCoverage, IncreasePercent, MaxBid.

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

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

но не более MaxBid.

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

Ограничения

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

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

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

Запрос

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

{
  "method": "setAuto",
  "params": { /* params */
    "Bids": [{  /* BidSetAutoItem */
      "CampaignId": (long),
      "AdGroupId": (long),
      "KeywordId": (long),
      "MaxBid": (long),
      "Position": ( "PREMIUMFIRST" | "PREMIUMBLOCK" | "FOOTERFIRST" | "FOOTERBLOCK" | "P11" | "P12" | "P13" | "P14" | "P21" | "P22" | "P23" | "P24" ),
      "IncreasePercent": (int),
      "CalculateBy": ( "VALUE" | "DIFF" ),
      "ContextCoverage": (int),
      "Scope": [( "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, IncreasePercent, CalculateBy, MaxBid. NETWORK — назначить ставки в сетях (ContextBid). Для расчета ставок используются значения, переданные в параметрах ContextCoverage, IncreasePercent, MaxBid.	Да
`MaxBid`	long	Ограничение на ставку, умноженное на 1 000 000. Целое число. Указывается в валюте рекламодателя. Ограничения представлены в справочнике валют, который можно получить с помощью метода Dictionaries.get, указав в запросе имя справочника Currencies.	Нет
`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


Структура 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, IncreasePercent, CalculateBy, MaxBid. NETWORK — назначить ставки в сетях (ContextBid). Для расчета ставок используются значения, переданные в параметрах ContextCoverage, IncreasePercent, MaxBid.	Да
`MaxBid`	long	Ограничение на ставку, умноженное на 1 000 000. Целое число. Указывается в валюте рекламодателя. Ограничения представлены в справочнике валют, который можно получить с помощью метода Dictionaries.get, указав в запросе имя справочника Currencies.	Нет
`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": { /* result */
    "SetAutoResults": [{  /* BidActionResult */
      "Warnings": [{  /* ExceptionNotification */
        "Code": (int), /* required */
        "Message": (string), /* required */
        "Details": (string)
      }, ... ],
      "Errors": [{  /* ExceptionNotification */
        "Code": (int), /* required */
        "Message": (string), /* required */
        "Details": (string)
     }, ... ],        
    "CampaignId": (long),
    "AdGroupId": (long),
    "KeywordId": (long) 
   }, ... ]
  }
}


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


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

Была ли статья полезна?

Расскажите, что вам не понравилось в статье:

set

Businesses: получение профилей организаций

В этой статье

Ограничения Запрос Ответ Примеры

set

Businesses: получение профилей организаций