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 знаков после запятой. Также допускаются смещения, отличные от «Z». Примеры: "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) заказа на размещение.

В интерфейсе Display & Video 360 это обозначено как «Цель».

budget

object ( InsertionOrderBudget )

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

bidStrategy

object ( BiddingStrategy )

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

reservationType

enum ( ReservationType )

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

optimizationObjective

enum ( OptimizationObjective )

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

InsertionOrderType

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

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

Перечисления
INSERTION_ORDER_TYPE_UNSPECIFIED Тип заказа на размещение не указан или неизвестен.
RTB Торги в реальном времени.
OVER_THE_TOP Чрезмерно.

КПЭ

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

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

  // Union field kpi_value can be only one of the following:
  "kpiAmountMicros": string,
  "kpiPercentageMicros": string,
  "kpiString": string
  // End of list of possible types for union field kpi_value.
}
Поля
kpiType

enum ( KpiType )

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

kpiAlgorithmId

string ( int64 format)

Необязательно. Идентификатор алгоритма назначения ставок, связанный с KPI_CUSTOM_IMPRESSION_VALUE_OVER_COST. Это поле игнорируется, если не выбран правильный KPI.

Поле объединения kpi_value . Обязательное. Значение KPI. Соответствующее поле соответствует kpi_type . kpi_value может быть только одним из следующих:
kpiAmountMicros

string ( int64 format)

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

Применимо, когда kpiType является одним из:

  • KPI_TYPE_CPM
  • KPI_TYPE_CPC
  • KPI_TYPE_CPA
  • KPI_TYPE_CPIAVC
  • KPI_TYPE_VCPM

Например: 1500000 представляет собой 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 Ключевым показателем эффективности является CPM (стоимость за тысячу показов).
KPI_TYPE_CPC KPI — это CPC (стоимость клика).
KPI_TYPE_CPA KPI — это CPA (стоимость за действие).
KPI_TYPE_CTR KPI — это процент CTR (кликабельности).
KPI_TYPE_VIEWABILITY KPI — процент видимости.
KPI_TYPE_CPIAVC Ключевым показателем эффективности является CPIAVC (стоимость показа аудио- и видеоматериалов по завершении).
KPI_TYPE_CPE Ключевым показателем эффективности является CPE (стоимость за взаимодействие).
KPI_TYPE_CPV KPI устанавливается в CPV (стоимость за просмотр).
KPI_TYPE_CLICK_CVR KPI — это процент конверсии кликов (конверсий за клик).
KPI_TYPE_IMPRESSION_CVR KPI — это процент конверсии показов (конверсий на показ).
KPI_TYPE_VCPM KPI — это VCPM (стоимость за тысячу просмотренных показов).
KPI_TYPE_VTR KPI — это процент просмотров на YouTube (количество просмотров на YouTube за показ).
KPI_TYPE_AUDIO_COMPLETION_RATE KPI — это процентное соотношение количества полных прослушиваний аудио на один показ.
KPI_TYPE_VIDEO_COMPLETION_RATE KPI — это процент завершения просмотра видео (количество полных просмотров видео за один показ).
KPI_TYPE_CPCL KPI устанавливается в CPCL (стоимость полного прослушивания аудио).
KPI_TYPE_CPCV KPI устанавливается в CPCV (стоимость полного просмотра видео).
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 Разрешить системе автоматически корректировать ставки и перераспределять бюджет по позициям, обеспечивающим оптимизацию производительности, определяемой ключевыми показателями kpi .

InsertionOrderBudgetSegment

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

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

string ( int64 format)

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

description

string

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

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

dateRange

object ( DateRange )

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

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

string ( int64 format)

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

Цель оптимизации

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

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

Методы

create

 Создает новый заказ на вставку.

delete

 Удаляет заказ на вставку.

get

 Получает заказ на вставку.

list

 Перечисляет заказы на размещение в рекламодателе.

listAssignedTargetingOptions

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

patch

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