REST Resource: advertisers.insertionOrders

Ресурс: InsertionOrder

Один заказ на размещение.

JSON-представление 
{
  "name": string,
  "advertiserId": string,
  "campaignId": string,
  "insertionOrderId": string,
  "displayName": string,
  "insertionOrderType": enum (InsertionOrderType),
  "entityStatus": enum (EntityStatus),
  "updateTime": string,
  "partnerCosts": [
    {
      object (PartnerCost)
    }
  ],
  "pacing": {
    object (Pacing)
  },
  "frequencyCap": {
    object (FrequencyCap)
  },
  "integrationDetails": {
    object (IntegrationDetails)
  },
  "kpi": {
    object (Kpi)
  },
  "budget": {
    object (InsertionOrderBudget)
  },
  "bidStrategy": {
    object (BiddingStrategy)
  },
  "reservationType": enum (ReservationType),
  "optimizationObjective": enum (OptimizationObjective)
}
Поля
name

string

Только для вывода. Название ресурса заказа на размещение.
advertiserId

string (int64 format)

Только для вывода. Уникальный идентификатор рекламодателя, которому принадлежит заказ на размещение.
campaignId

string (int64 format)

Обязательно. Не меняется. Уникальный идентификатор кампании, к которой относится заказ на размещение.
insertionOrderId

string (int64 format)

Только для вывода. Уникальный идентификатор заказа на размещение. Назначается системой.
displayName

string

Обязательно. Отображаемое название заказа на размещение.

Должно быть закодировано в UTF-8 и иметь максимальный размер 240 байт.
insertionOrderType

enum (InsertionOrderType)

Необязательное поле. Тип заказа на размещение.

Если это поле не заполнено при создании, по умолчанию используется значение RTB.
entityStatus

enum (EntityStatus)

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

  • Для метода insertionOrders.create разрешено только значение ENTITY_STATUS_DRAFT. Чтобы активировать заказ на размещение, используйте метод insertionOrders.patch и измените статус на ENTITY_STATUS_ACTIVE после создания.
  • Заказу на размещение нельзя вернуть статус "ENTITY_STATUS_DRAFT".
  • Заказу на размещение нельзя присвоить статус ENTITY_STATUS_ACTIVE, если родительская кампания неактивна.
updateTime

string (Timestamp format)

Только для вывода. Временная метка последнего обновления заказа на размещение. Назначается системой.

Используется формат RFC 3339. Результат всегда будет Z-нормализованным, и в нем будут использоваться цифры дробных частей 0, 3, 6 или 9. Допустимы и другие типы нормализации. Примеры: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30".
partnerCosts[]

object (PartnerCost)

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

Если это поле отсутствует или не заполнено в методе insertionOrders.create, то новый заказ на размещение унаследует стоимость услуг партнера из его настроек.
pacing

object (Pacing)

Обязательно. Настройка скорости расходования бюджета в заказе на размещение.

pacingType PACING_TYPE_ASAP несовместим с pacingPeriod PACING_PERIOD_FLIGHT.
frequencyCap

object (FrequencyCap)

Обязательно. Настройка ограничения частоты показов для заказа на размещение.
integrationDetails

object (IntegrationDetails)

Необязательное поле. Дополнительные сведения об интеграции заказа на размещение.
kpi

object (Kpi)

Обязательно. Ключевой показатель эффективности (KPI) заказа на размещение.

В интерфейсе Дисплея и Видео 360 она называется целью.
budget

object (InsertionOrderBudget)

Обязательно. Настройки распределения бюджета для заказа на размещение.
bidStrategy

object (BiddingStrategy)

Необязательное поле. Стратегия назначения ставок для заказа на размещение. По умолчанию задано значение fixedBid.

Если в поле budget (automationType) задано значение INSERTION_ORDER_AUTOMATION_TYPE_BUDGET или INSERTION_ORDER_AUTOMATION_TYPE_BID_BUDGET, то заказ на размещение будет применять эту стратегию назначения ставок к своим позициям. Если принудительно назначенная стратегия назначения ставок несовместима с настройкой enableOptimizedTargeting позиции, то настройка оптимизированного таргетинга будет изменена.
reservationType

enum (ReservationType)

Только для вывода. Тип резервирования заказа на размещение.
optimizationObjective

enum (OptimizationObjective)

Обязательно. Цель оптимизации заказа на размещение.

InsertionOrderType

Возможные типы заказа на размещение.

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

Перечисления
INSERTION_ORDER_TYPE_UNSPECIFIED Тип заказа на размещение не указан или неизвестен.
RTB Назначение ставок в реальном времени.
OVER_THE_TOP Инвентарь с поддержкой технологии OTT.
OUT_OF_HOME Наружная реклама.

КПЭ

Настройки, которые управляют ключевым показателем эффективности (KPI) заказа на размещение.

JSON-представление 
{
  "kpiType": enum (KpiType),
  "kpiAlgorithmId": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "kpiAmountMicros": string,
  "kpiPercentageMicros": string,
  "kpiString": string
  // End of mutually exclusive fields.
}
Поля
kpiType

enum (KpiType)

Обязательно. Тип KPI.
kpiAlgorithmId

string (int64 format)

Необязательное поле. Идентификатор алгоритма специальных ставок, связанный с KPI_CUSTOM_IMPRESSION_VALUE_OVER_COST. Если не выбран подходящий KPI, это поле игнорируется.
Обязательно. Значение KPI. Соответствующее поле относится к kpi_type. Ниже приведен список взаимоисключающих полей. В ответе будет задано не более одного из следующих полей:
kpiAmountMicros

string (int64 format)

Целевая сумма в микроединицах валюты рекламодателя.

Применимо, если kpiType – одно из следующих значений:

  • KPI_TYPE_CPM
  • KPI_TYPE_CPC
  • KPI_TYPE_CPA
  • KPI_TYPE_CPIAVC
  • KPI_TYPE_VCPM

Например, 1 500 000 соответствует 1,5 стандартной единицы валюты.
kpiPercentageMicros

string (int64 format)

Десятичное представление целевого процента в микро.

Применимо, если kpiType – одно из следующих значений:

  • KPI_TYPE_CTR
  • KPI_TYPE_VIEWABILITY
  • KPI_TYPE_CLICK_CVR
  • KPI_TYPE_IMPRESSION_CVR
  • KPI_TYPE_VTR
  • KPI_TYPE_AUDIO_COMPLETION_RATE
  • KPI_TYPE_VIDEO_COMPLETION_RATE

Например, 70000 означает 7% (десятичное значение 0,07).
kpiString

string

Строка KPI, которая может быть пустой. Должно быть в кодировке UTF-8 и содержать не более 100 символов.

Применяется, если для параметра kpiType задано значение KPI_TYPE_OTHER.
Конец взаимоисключающих полей.

KpiType

Возможные типы ключевых показателей эффективности (KPI).

Перечисления
KPI_TYPE_UNSPECIFIED Тип KPI не указан или неизвестен в этой версии.
KPI_TYPE_CPM KPI – цена за тысячу показов.
KPI_TYPE_CPC KPI – цена за клик.
KPI_TYPE_CPA KPI – цена за конверсию.
KPI_TYPE_CTR KPI – это процент CTR (показатель CTR).
KPI_TYPE_VIEWABILITY KPI – процент видимости.
KPI_TYPE_CPIAVC KPI – цена за показ до конца в видимой области экрана с включенным звуком.
KPI_TYPE_CPE KPI – цена за взаимодействие.
KPI_TYPE_CPV KPI задается в виде цены за просмотр.
KPI_TYPE_CLICK_CVR KPI – коэффициент конверсии по кликам (конверсии на клик) в процентах.
KPI_TYPE_IMPRESSION_CVR KPI – это коэффициент конверсии по показам (конверсии на показ) в процентах.
KPI_TYPE_VCPM KPI – цена за тысячу показов в видимой области экрана.
KPI_TYPE_VTR KPI – коэффициент просмотров на YouTube (просмотры на YouTube на показ) в процентах.
KPI_TYPE_AUDIO_COMPLETION_RATE KPI – доля прослушиваний до конца (количество полных прослушиваний аудиообъявления на показ) в процентах.
KPI_TYPE_VIDEO_COMPLETION_RATE KPI – доля просмотров видео до конца (количество просмотров видео до конца на показ) в процентах.
KPI_TYPE_CPCL В качестве KPI задана цена за прослушивание до конца.
KPI_TYPE_CPCV KPI – цена за просмотр видеообъявлений до конца.
KPI_TYPE_TOS10 KPI задается как доля времени на экране, равная 10 секундам или более (процент отслеживаемых показов без возможности пропуска, которые длились не менее 10 секунд).
KPI_TYPE_MAXIMIZE_PACING KPI настроен на максимальное влияние на бренд с приоритетом на расходование всего бюджета.
KPI_TYPE_CUSTOM_IMPRESSION_VALUE_OVER_COST KPI задается как специальная ценность показа, деленная на стоимость.
KPI_TYPE_OTHER KPI – это другое значение.

InsertionOrderBudget

Настройки, определяющие, как распределяется бюджет заказа на размещение.

JSON-представление 
{
  "budgetUnit": enum (BudgetUnit),
  "automationType": enum (InsertionOrderAutomationType),
  "budgetSegments": [
    {
      object (InsertionOrderBudgetSegment)
    }
  ]
}
Поля
budgetUnit

enum (BudgetUnit)

Обязательно. Не меняется. Единица бюджета определяет, на чем основан бюджет – на денежных средствах или на показах.
automationType

enum (InsertionOrderAutomationType)

Необязательное поле. Тип автоматизации, используемый для управления ставками и бюджетом заказа на размещение.

Если это поле не заполнено при создании, по умолчанию используется значение INSERTION_ORDER_AUTOMATION_TYPE_NONE.
budgetSegments[]

object (InsertionOrderBudgetSegment)

Обязательно. Список сегментов бюджета. Сегменты бюджета позволяют использовать особые настройки бюджета в определенные периоды выполнения заказа на размещение.

InsertionOrderAutomationType

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

Перечисления
INSERTION_ORDER_AUTOMATION_TYPE_UNSPECIFIED Вариант автоматизации заказа на размещение не указан или неизвестен в этой версии.
INSERTION_ORDER_AUTOMATION_TYPE_BUDGET Автоматическое распределение бюджета. Разрешите системе автоматически перераспределять бюджет в пользу позиций, которые демонстрируют наибольшую эффективность по показателю "kpi". Настройки ставок не автоматизированы.
INSERTION_ORDER_AUTOMATION_TYPE_NONE Ставки и бюджеты не автоматизируются на уровне заказа на размещение. Ставку и бюджет необходимо вручную настроить на уровне позиции.
INSERTION_ORDER_AUTOMATION_TYPE_BID_BUDGET Разрешите системе автоматически корректировать ставки и перераспределять бюджет между позициями, чтобы оптимизировать эффективность, определяемую показателем "bidStrategy".

InsertionOrderBudgetSegment

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

JSON-представление 
{
  "budgetAmountMicros": string,
  "description": string,
  "dateRange": {
    object (DateRange)
  },
  "campaignBudgetId": string
}
Поля
budgetAmountMicros

string (int64 format)

Обязательно. Сумма, которая будет потрачена в рамках заказа на размещение за указанный период (dateRange). Сумма указывается в миллионных долях валюты. Укажите значение больше нуля. Например, 500000000 означает 500 стандартных единиц валюты.
description

string

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

Должен быть в кодировке UTF-8.
dateRange

object (DateRange)

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

  • При создании нового сегмента бюджета даты startDate и endDate должны быть в будущем.
  • У существующего сегмента бюджета с startDate в прошлом можно изменить endDate, но нельзя изменить startDate.
  • endDate должно быть не ранее startDate и не позднее 2037 года.
campaignBudgetId

string (int64 format)

Необязательное поле. budgetId бюджета кампании, частью которого является этот сегмент бюджета заказа на размещение.

OptimizationObjective

Возможные типы целей оптимизации.

Перечисления
OPTIMIZATION_OBJECTIVE_UNSPECIFIED Значение типа не указано или неизвестно в этой версии.
CONVERSION Отдавайте приоритет показам, которые позволяют увеличить продажи и количество конверсий.
CLICK Отдавайте приоритет показам, которые позволяют увеличить трафик сайтов, приложений, магазинов приложений.
BRAND_AWARENESS Отдавайте приоритет показам с определенным уровнем качества.
CUSTOM Цель определяется назначенным алгоритмом специальных ставок.
NO_OBJECTIVE Цель не определена. Можно использовать любой KPI или стратегию назначения ставок.

Методы

create

 Создает заказ на размещение.

delete

 Удаляет заказ на размещение.

get

 Получает заказ на размещение.

list

 Возвращает список заказов на размещение, относящихся к рекламодателю.

patch

 Обновляет существующий заказ на размещение.