REST Resource: advertisers.lineItems

Ресурс: LineItem

Одна позиция.

JSON-представление 
{
  "name": string,
  "advertiserId": string,
  "campaignId": string,
  "insertionOrderId": string,
  "lineItemId": string,
  "displayName": string,
  "lineItemType": enum (LineItemType),
  "entityStatus": enum (EntityStatus),
  "updateTime": string,
  "partnerCosts": [
    {
      object (PartnerCost)
    }
  ],
  "flight": {
    object (LineItemFlight)
  },
  "budget": {
    object (LineItemBudget)
  },
  "pacing": {
    object (Pacing)
  },
  "frequencyCap": {
    object (FrequencyCap)
  },
  "partnerRevenueModel": {
    object (PartnerRevenueModel)
  },
  "conversionCounting": {
    object (ConversionCountingConfig)
  },
  "creativeIds": [
    string
  ],
  "bidStrategy": {
    object (BiddingStrategy)
  },
  "integrationDetails": {
    object (IntegrationDetails)
  },
  "inventorySourceIds": [
    string
  ],
  "targetingExpansion": {
    object (TargetingExpansionConfig)
  },
  "warningMessages": [
    enum (LineItemWarningMessage)
  ],
  "mobileApp": {
    object (MobileApp)
  },
  "reservationType": enum (ReservationType),
  "excludeNewExchanges": boolean
}
Поля
name

string

Только вывод. Имя ресурса позиции.

advertiserId

string ( int64 format)

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

campaignId

string ( int64 format)

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

insertionOrderId

string ( int64 format)

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

lineItemId

string ( int64 format)

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

displayName

string

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

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

lineItemType

enum ( LineItemType )

Необходимый. Неизменяемый. Тип позиции.

entityStatus

enum ( EntityStatus )

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

  • Для метода lineItems.create разрешен только ENTITY_STATUS_DRAFT . Чтобы активировать позицию, используйте метод lineItems.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 )

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

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

flight

object ( LineItemFlight )

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

budget

object ( LineItemBudget )

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

pacing

object ( Pacing )

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

frequencyCap

object ( FrequencyCap )

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

Поле maxImpressions в этом объекте настроек необходимо использовать при назначении ограниченного ограничения.

partnerRevenueModel

object ( PartnerRevenueModel )

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

conversionCounting

object ( ConversionCountingConfig )

Настройка отслеживания конверсий позиции.

creativeIds[]

string ( int64 format)

Идентификаторы объявлений, связанных с позицией.

bidStrategy

object ( BiddingStrategy )

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

integrationDetails

object ( IntegrationDetails )

Подробности интеграции позиции.

inventorySourceIds[]

string ( int64 format)

Идентификаторы источников частного инвентаря, назначенных позиции.

targetingExpansion

object ( TargetingExpansionConfig )

Оптимизированные настройки таргетинга позиции.

Эта конфигурация применима только к медийным, видео- и аудиопозициям, в которых используется автоматическое назначение ставок и таргетинг на списки подходящей аудитории.

warningMessages[]

enum ( LineItemWarningMessage )

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

mobileApp

object ( MobileApp )

Мобильное приложение, рекламируемое позицией.

Это применимо только в том случае, если lineItemType имеет значение LINE_ITEM_TYPE_DISPLAY_MOBILE_APP_INSTALL или LINE_ITEM_TYPE_VIDEO_MOBILE_APP_INSTALL .

reservationType

enum ( ReservationType )

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

excludeNewExchanges

boolean

Следует ли исключить новые биржи из автоматического таргетинга позиции. По умолчанию это поле имеет значение false.

LineItemType

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

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

Перечисления
LINE_ITEM_TYPE_UNSPECIFIED

Значение типа не указано или неизвестно в этой версии.

Позиции этого типа и их таргетинг нельзя создавать или обновлять с помощью API.

LINE_ITEM_TYPE_DISPLAY_DEFAULT Графические, HTML5, нативные или мультимедийные объявления.
LINE_ITEM_TYPE_DISPLAY_MOBILE_APP_INSTALL Показывайте рекламу, которая увеличивает количество установок приложения.
LINE_ITEM_TYPE_VIDEO_DEFAULT Видеореклама продается по цене за тысячу показов для различных сред.
LINE_ITEM_TYPE_VIDEO_MOBILE_APP_INSTALL Видеореклама, которая увеличивает количество установок приложения.
LINE_ITEM_TYPE_DISPLAY_MOBILE_APP_INVENTORY

Медийная реклама, показываемая на инвентаре мобильных приложений.

Позиции этого типа и их таргетинг нельзя создавать или обновлять с помощью API.

LINE_ITEM_TYPE_VIDEO_MOBILE_APP_INVENTORY

Видеореклама показывается на инвентаре мобильных приложений.

Позиции этого типа и их таргетинг нельзя создавать или обновлять с помощью API.

LINE_ITEM_TYPE_AUDIO_DEFAULT Аудиообъявления RTB, продаваемые для различных сред.
LINE_ITEM_TYPE_VIDEO_OVER_THE_TOP Чрезмерная реклама присутствует в заказах на размещение OTT. Этот тип применим только к позициям с заказом на размещение insertionOrderType OVER_THE_TOP .

LineItemПолет

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

JSON-представление 
{
  "flightDateType": enum (LineItemFlightDateType),
  "dateRange": {
    object (DateRange)
  },
  "triggerId": string
}
Поля
flightDateType

enum ( LineItemFlightDateType )

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

dateRange

object ( DateRange )

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

  • Требуется, если flightDateType имеет значение LINE_ITEM_FLIGHT_DATE_TYPE_CUSTOM . Вывод только иначе.
  • При создании нового рейса и startDate , и endDate должны находиться в будущем.
  • Существующий рейс с startDate в прошлом имеет изменяемый endDate но неизменяемый startDate .
  • endDate должна быть startDate или позже, оба до 2037 года.
triggerId

string ( int64 format)

Идентификатор ручного триггера, связанного с кампанией.

  • Требуется, если flightDateType имеет значение LINE_ITEM_FLIGHT_DATE_TYPE_TRIGGER . Не должно быть установлено иначе.
  • Если этот параметр установлен, даты истечения позиции наследуются из родительского заказа на размещение.
  • Активные позиции будут расходовать средства, когда выбранный триггер активируется в пределах сроков действия родительского заказа на размещение.

Предупреждение. Позиции, в которых используются ручные триггеры, больше не отображаются в Display & Video 360. Действие этого поля будет прекращено 1 августа 2023 г. Для получения дополнительной информации прочтите наше объявление об прекращении поддержки функции .

LineItemFlightDateType

Возможные типы дат окончания действия позиции.

Перечисления
LINE_ITEM_FLIGHT_DATE_TYPE_UNSPECIFIED Значение типа не указано или неизвестно в этой версии.
LINE_ITEM_FLIGHT_DATE_TYPE_INHERITED Даты выполнения позиции наследуются из родительского заказа на размещение.
LINE_ITEM_FLIGHT_DATE_TYPE_CUSTOM В позиции используются собственные даты начала показа.
LINE_ITEM_FLIGHT_DATE_TYPE_TRIGGER

В позиции используется триггер.

Предупреждение. Позиции, использующие ручные триггеры, больше не отображаются в Display & Video 360. Это значение перестанет действовать 1 августа 2023 г. Для получения дополнительной информации прочтите наше объявление об прекращении поддержки функции .

ПозицияБюджет

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

JSON-представление 
{
  "budgetAllocationType": enum (LineItemBudgetAllocationType),
  "budgetUnit": enum (BudgetUnit),
  "maxAmount": string
}
Поля
budgetAllocationType

enum ( LineItemBudgetAllocationType )

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

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

budgetUnit

enum ( BudgetUnit )

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

maxAmount

string ( int64 format)

Максимальная сумма бюджета, которую потратит позиция. Должно быть больше 0.

Когда budgetAllocationType имеет значение:

  • LINE_ITEM_BUDGET_ALLOCATION_TYPE_AUTOMATIC , это поле неизменяемо и устанавливается системой.
  • LINE_ITEM_BUDGET_ALLOCATION_TYPE_FIXED , если budgetUnit :
    • BUDGET_UNIT_CURRENCY , это поле представляет максимальную сумму бюджета, которую можно потратить, в микро валютах рекламодателя. Например, 1500000 представляет собой 1,5 стандартных единицы валюты.
    • BUDGET_UNIT_IMPRESSIONS , в этом поле указано максимальное количество показов.
  • LINE_ITEM_BUDGET_ALLOCATION_TYPE_UNLIMITED это поле неприменимо и будет игнорироваться системой.

LineItemBudgetAllocationType

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

Перечисления
LINE_ITEM_BUDGET_ALLOCATION_TYPE_UNSPECIFIED Значение типа не указано или неизвестно в этой версии.
LINE_ITEM_BUDGET_ALLOCATION_TYPE_AUTOMATIC Для позиции включено автоматическое распределение бюджета.
LINE_ITEM_BUDGET_ALLOCATION_TYPE_FIXED Для позиции выделяется фиксированная максимальная сумма бюджета.
LINE_ITEM_BUDGET_ALLOCATION_TYPE_UNLIMITED К позиции не применяется ограничение бюджета.

Партнерская модель дохода

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

JSON-представление 
{
  "markupType": enum (PartnerRevenueModelMarkupType),
  "markupAmount": string
}
Поля
markupType

enum ( PartnerRevenueModelMarkupType )

Необходимый. Тип наценки партнерской модели дохода.

markupAmount

string ( int64 format)

Необходимый. Сумма наценки партнерской модели дохода. Должно быть больше или равно 0.

  • Если markupType установлено значение PARTNER_REVENUE_MODEL_MARKUP_TYPE_CPM , это поле представляет наценку за тысячу показов в микронах валюты рекламодателя. Например, 1500000 представляет собой 1,5 стандартных единицы валюты.
  • Если markupType установлено значение PARTNER_REVENUE_MODEL_MARKUP_TYPE_MEDIA_COST_MARKUP , это поле представляет процентную надбавку к стоимости рекламы в миллисах. Например, 100 представляет собой 0,1% (десятичное 0,001).
  • Если для markupType установлено значение PARTNER_REVENUE_MODEL_MARKUP_TYPE_TOTAL_MEDIA_COST_MARKUP , это поле представляет общую процентную надбавку к стоимости рекламы в миллисах. Например, 100 представляет собой 0,1% (десятичное 0,001).

PartnerRevenueModelMarkupType

Возможные типы наценок партнерской модели дохода.

Перечисления
PARTNER_REVENUE_MODEL_MARKUP_TYPE_UNSPECIFIED Значение типа не указано или неизвестно в этой версии.
PARTNER_REVENUE_MODEL_MARKUP_TYPE_CPM Рассчитайте доход партнера на основе фиксированной цены за тысячу показов.
PARTNER_REVENUE_MODEL_MARKUP_TYPE_MEDIA_COST_MARKUP

Рассчитайте доход партнера на основе процентной надбавки к стоимости рекламы.

PARTNER_REVENUE_MODEL_MARKUP_TYPE_TOTAL_MEDIA_COST_MARKUP Рассчитайте доход партнера на основе процентной надбавки к общей стоимости рекламы, которая включает в себя все партнерские расходы и затраты на передачу данных.

ConversionCountingConfig

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

Все конверсии после клика будут засчитаны. Для подсчета конверсий после просмотра можно установить процентное значение.

JSON-представление 
{
  "postViewCountPercentageMillis": string,
  "floodlightActivityConfigs": [
    {
      object (TrackingFloodlightActivityConfig)
    }
  ]
}
Поля
postViewCountPercentageMillis

string ( int64 format)

Процент учитываемых конверсий после просмотра, в миллисах (1/1000 процента). Должно быть от 0 до 100 000 включительно.

Например, чтобы отслеживать 50 % конверсий после клика, установите значение 50 000.

floodlightActivityConfigs[]

object ( TrackingFloodlightActivityConfig )

Конфигурации действий Floodlight, используемые для отслеживания конверсий.

Количество подсчитанных конверсий представляет собой сумму всех конверсий, подсчитанных всеми идентификаторами действий Floodlight, указанными в этом поле.

ОтслеживаниеFloodlightActivityConfig

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

JSON-представление 
{
  "floodlightActivityId": string,
  "postClickLookbackWindowDays": integer,
  "postViewLookbackWindowDays": integer
}
Поля
floodlightActivityId

string ( int64 format)

Необходимый. Идентификатор действия Floodlight.

postClickLookbackWindowDays

integer

Необходимый. Количество дней после клика по объявлению, в течение которых может быть засчитана конверсия. Должно быть от 0 до 90 включительно.

postViewLookbackWindowDays

integer

Необходимый. Количество дней после просмотра объявления, в течение которых может быть засчитана конверсия. Должно быть от 0 до 90 включительно.

Конфигурация расширения таргетинга

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

JSON-представление 
{
  "targetingExpansionLevel": enum (TargetingExpansionLevel),
  "excludeFirstPartyAudience": boolean
}
Поля
targetingExpansionLevel

enum ( TargetingExpansionLevel )

Необходимый. Включен ли оптимизированный таргетинг.

Это поле поддерживает следующие значения:

  • NO_EXPANSION : оптимизированный таргетинг отключен.
  • LEAST_EXPANSION : включен оптимизированный таргетинг.

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

NO_EXPANSION будет значением по умолчанию для поля и будет присвоено автоматически, если вы не установите это поле.

excludeFirstPartyAudience
(deprecated)

boolean

Исключить ли собственные аудитории из использования при расширении таргетинга.

Это поле устарело с запуском оптимизированного таргетинга .

В этом поле будет установлено значение false . Если для этого поля установлено значение true , когда оно устарело, все положительные таргетинги на собственную аудиторию, назначенные этой позиции, будут заменены отрицательными таргетингами на те же собственные аудитории, чтобы обеспечить дальнейшее исключение этих аудиторий.

Уровень расширения таргетинга

Настройка оптимизированного таргетинга.

Перечисления
TARGETING_EXPANSION_LEVEL_UNSPECIFIED Параметр оптимизированного таргетинга в этой версии не указан или неизвестен.
NO_EXPANSION Оптимизированный таргетинг отключен.
LEAST_EXPANSION Оптимизированный таргетинг включен.
SOME_EXPANSION

Если используется, автоматически будет установлено значение LEAST_EXPANSION .

BALANCED_EXPANSION

Если используется, автоматически будет установлено значение LEAST_EXPANSION .

MORE_EXPANSION

Если используется, автоматически будет установлено значение LEAST_EXPANSION .

MOST_EXPANSION

Если используется, автоматически будет установлено значение LEAST_EXPANSION .

LineItemПредупреждениеСообщение

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

Перечисления
LINE_ITEM_WARNING_MESSAGE_UNSPECIFIED Не указано или неизвестно.
INVALID_FLIGHT_DATES Для этой позиции указаны недопустимые даты полета. Позиция не будет показываться.
EXPIRED Дата окончания этой позиции уже в прошлом.
PENDING_FLIGHT Показ этой позиции начнется в будущем.
ALL_PARTNER_ENABLED_EXCHANGES_NEGATIVELY_TARGETED Все партнерские биржи настроены негативно. Позиция не будет показываться.
INVALID_INVENTORY_SOURCE Ни один активный источник инвентаря не выбран. Позиция не будет показываться.
APP_INVENTORY_INVALID_SITE_TARGETING Таргетинг этой позиции на приложения и URL-адреса не включает мобильные приложения. Для этого типа позиции необходимо включить мобильные приложения в таргетинг на канал, список сайтов или приложения. Позиция не будет показываться.
APP_INVENTORY_INVALID_AUDIENCE_LISTS Эта позиция не ориентирована ни на одного мобильного пользователя. Для этого типа позиции необходимо настроить таргетинг на список пользователей мобильных устройств. Позиция не будет показываться.
NO_VALID_CREATIVE Эта позиция не содержит действительных объявлений. Позиция не будет показываться.
PARENT_INSERTION_ORDER_PAUSED Заказ на размещение этой позиции приостановлен. Позиция не будет показываться.
PARENT_INSERTION_ORDER_EXPIRED Дата окончания заказа на размещение этой позиции установлена ​​в прошлом. Позиция не будет показываться.
NO_POSITIVE_AUDIENCE_LIST_TARGETED Эта позиция не ориентирована ни на какие списки аудитории, что может привести к слишком быстрому расходованию бюджета.
APP_INSTALL_NO_CONVERSION_PIXEL Для этой позиции, ориентированной на установку приложения, не настроен ни один пиксель конверсии.
TARGETING_REVOKED_OR_CLOSED_USER_LIST Эта позиция нацелена на один или несколько списков пользователей, которые больше не доступны. В будущем это приведет к невозможности показа позиции, поэтому рассмотрите возможность удаления этих списков из вашего таргетинга.
APP_INSTALL_NO_OPTIMAL_BIDDING_STRATEGY Для этой позиции, ориентированной на установку приложения, не задана оптимальная стратегия назначения ставок.
CREATIVE_SIZE_NOT_IN_USE_FOR_TARGETED_DEALS Сделки, на которые нацелена эта позиция, допускают размеры креативов, которые не используются. Это может ограничить показ или эффективность позиции.
NO_CREATIVE_FOR_TARGETED_DEALS Эта позиция не содержит креативов для целевых сделок.
TARGETING_DEPRECATED_GEO_TARGET Таргетинг этой позиции настроен на устаревшую географическую цель.
DEPRECATED_FIRST_PARTY_AUDIENCE_EXCLUSION

В этой позиции используется параметр excludeFirstPartyAudience , который устарел и будет отключен после 25 марта 2023 г.

Обновите интеграцию API, чтобы напрямую исключать любые собственные аудитории, использующие таргетинг на аудиторию , до 25 марта 2023 г., чтобы учесть прекращение действия поля excludeFirstPartyAudience .

Мобильное приложение

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

JSON-представление 
{
  "appId": string,
  "platform": enum (Platform),
  "displayName": string,
  "publisher": string
}
Поля
appId

string

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

Приложения Android идентифицируются по идентификатору пакета, используемому магазином Android Play, например com.google.android.gm .

Приложения iOS идентифицируются по девятизначному идентификатору приложения, используемому магазином приложений Apple, например 422689480 .

platform

enum ( Platform )

Только вывод. Платформа приложений.

displayName

string

Только вывод. Имя приложения.

publisher

string

Только вывод. Издатель приложения.

Платформа

Возможные платформы мобильных приложений.

Перечисления
PLATFORM_UNSPECIFIED Платформа не указана.
IOS iOS-платформа.
ANDROID Платформа Андроид.

Методы

bulkEditLineItemAssignedTargetingOptions

 Массовое изменение параметров таргетинга в рамках одной позиции.

bulkListLineItemAssignedTargetingOptions

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

create

 Создает новую позицию.

delete

 Удаляет позицию.

generateDefault

 Создает новую позицию с настройками (включая таргетинг), унаследованными от заказа на размещение entity_status и ENTITY_STATUS_DRAFT .

get

 Получает позицию.

list

 Перечисляет позиции рекламодателя.

patch

 Обновляет существующую позицию.