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)

仅限输出。广告订单所属广告客户的唯一 ID。
campaignId

string (int64 format)

必需。不可变。广告订单所属广告系列的唯一 ID。
insertionOrderId

string (int64 format)

仅限输出。广告订单的唯一 ID。由系统分配。
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 规范化（即转换为 UTC 零时区格式并在末尾附加 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 OTT 服务。
OUT_OF_HOME 户外广告。

KPI

用于控制广告订单的关键绩效指标 (KPI) 的设置。

JSON 表示法 
{
  "kpiType": enum (KpiType),
  "kpiAlgorithmId": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "kpiAmountMicros": string,
  "kpiPercentageMicros": string,
  "kpiString": string
  // End of mutually exclusive fields.
}
字段
kpiType

enum (KpiType)

必需。KPI 的类型。
kpiAlgorithmId

string (int64 format)

可选。与 KPI_CUSTOM_IMPRESSION_VALUE_OVER_COST 关联的自定义出价算法 ID。如果未选择正确的 KPI，系统会忽略此字段。
必需。KPI 的值。相关字段对应于 kpi_type。以下是互斥字段的列表。在响应中，最多只能设置其中一个字段：
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 类型未知。
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 为其他值。

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 允许系统自动调整出价并将预算转移到效果更好的订单项，以优化bidStrategy定义的效果。

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。

OptimizationObjective

优化目标的可能类型。

枚举
OPTIMIZATION_OBJECTIVE_UNSPECIFIED 此版本中未指定类型值，或类型值未知。
CONVERSION 优先认购可提高销售额和转化次数的展示机会。
CLICK 优先认购可为网站、应用和应用商店带来更多流量的展示机会。
BRAND_AWARENESS 优先认购特定质量的展示机会。
CUSTOM 目标由分配的自定义出价算法定义。
NO_OBJECTIVE 未定义目标。可以使用任何 KPI 或出价策略。

方法

create

 创建新的广告订单。

delete

 删除广告订单。

get

 获取广告订单。

list

 列出广告客户中的广告订单。

patch

 更新现有广告订单。