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 .

Если для поля 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 Чрезмерно.

Кпи

Настройки, определяющие ключевой показатель эффективности (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

Например: 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) — это 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 )

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

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

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