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)

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

Временная метка в формате RFC3339 UTC «Зулу» с наносекундным разрешением и до девяти дробных цифр. Примеры: "2014-10-02T15:01:23Z" и "2014-10-02T15:01:23.045123456Z" .

partnerCosts[]

object ( PartnerCost )

Расходы партнера, связанные с заказом на размещение.

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

pacing

object ( Pacing )

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

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 )

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

Это поле доступно только клиентам из белого списка. Если клиент не внесен в белый список, это поле будет пустым, и попытки его установить вернут ошибку.

Инсертинордертипе

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

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

Перечисления
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 )

Необходимый. Тип КПЭ.

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

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

Применимо, когда kpiType равен KPI_TYPE_OTHER .

Тип Kpi

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

Перечисления
KPI_TYPE_UNSPECIFIED В этой версии тип KPI не указан или неизвестен.
KPI_TYPE_CPM KPI — CPM (стоимость за тысячу показов).
KPI_TYPE_CPC KPI — CPC (стоимость за клик).
KPI_TYPE_CPA KPI — CPA (стоимость за действие).
KPI_TYPE_CTR KPI — это процент CTR (рейтинг кликов).
KPI_TYPE_VIEWABILITY KPI — процент видимости.
KPI_TYPE_CPIAVC KPI — CPIAVC (цена за показ слышна и видна при завершении).
KPI_TYPE_CPE KPI — 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 — это какое-то другое значение.

Бюджет заказа на вставку

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

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

enum ( BudgetUnit )

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

automationType

enum ( InsertionOrderAutomationType )

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

Если это поле не указано при создании, значение по умолчанию равно INSERTION_ORDER_AUTOMATION_TYPE_NONE .

budgetSegments[]

object ( InsertionOrderBudgetSegment )

Необходимый. Перечень сегментов бюджета. Используйте сегмент бюджета, чтобы указать конкретный бюджет на определенный период времени, в течение которого действует заказ на размещение.

Инсерционордеравтоматионтипе

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

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

Инсерционордербюджетсегмент

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

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

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