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

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

advertiser Id

string ( int64 format)

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

campaign Id

string ( int64 format)

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

insertion Order Id

string ( int64 format)

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

display Name

string

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

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

insertion Order Type

enum ( InsertionOrderType )

Тип заказа на размещение.

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

entity Status

enum ( EntityStatus )

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

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

string ( Timestamp format)

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

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

partner Costs[]

object ( PartnerCost )

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

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

pacing

object ( Pacing )

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

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

frequency Cap

object ( FrequencyCap )

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

integration Details

object ( IntegrationDetails )

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

kpi

object ( Kpi )

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

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

budget

object ( InsertionOrderBudget )

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

bid Strategy

object ( BiddingStrategy )

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

reservation Type

enum ( ReservationType )

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

optimization Objective

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.
}
Поля
kpi Type

enum ( KpiType )

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

kpi Algorithm Id

string ( int64 format)

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

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

string ( int64 format)

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

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

  • KPI_TYPE_CPM
  • KPI_TYPE_CPC
  • KPI_TYPE_CPA
  • KPI_TYPE_CPIAVC
  • KPI_TYPE_VCPM

Например: 1500000 представляет собой 1,5 стандартных единицы валюты.

kpi Percentage Micros

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).

kpi String

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)
    }
  ]
}
Поля
budget Unit

enum ( BudgetUnit )

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

automation Type

enum ( InsertionOrderAutomationType )

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

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

budget Segments[]

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
}
Поля
budget Amount Micros

string ( int64 format)

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

description

string

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

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

date Range

object ( DateRange )

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

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

string ( int64 format)

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

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

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

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

Методы

create

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

delete

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

get

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

list

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

list Assigned Targeting Options

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

patch

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