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，并使用 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。
reservationType

enum (ReservationType)

仅限输出。广告订单的预订类型。
optimizationObjective

enum (OptimizationObjective)

必需。相应广告订单的优化目标。

InsertionOrderType

广告订单的可能类型。

广告订单的类型决定了哪些设置和选项适用，例如广告格式或定位选项。

枚举
INSERTION_ORDER_TYPE_UNSPECIFIED 未指定或未知广告订单类型。
RTB 实时出价。
OVER_THE_TOP OTT 服务。

KPI

用于控制广告订单的关键绩效指标 (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 关联的自定义出价算法 ID。如果未选择合适的 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

一个 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 是点击率百分比。
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 允许系统自动调整出价并将预算转移到所属订单项，以优化由 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。

OptimizationObjective

优化目标的可能类型。

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

方法

create

 创建新的广告订单。

delete

 删除广告订单。

get

 获取广告订单。

list

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

listAssignedTargetingOptions

 列出广告订单在各种定位类型中已分配的定位选项。

patch

 更新现有插播订单。