REST Resource: advertisers.insertionOrders

资源：广告订单

单个广告订单。

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)

仅限输出。上次更新广告订单时的时间戳。由系统分配。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
partnerCosts[]

object (PartnerCost)

与广告订单关联的合作伙伴费用。

如果 insertionOrders.create 方法中不存在此值或值为空，则新创建的广告订单将继承合作伙伴设置中的合作伙伴费用。
pacing

object (Pacing)

必需。广告订单的预算支出速度设置。
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)

可选。广告订单的优化目标。

此字段仅适用于列入许可名单的客户。如果客户不在许可名单内，此字段将为 null，如果尝试设置此字段，则会返回错误。

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 是点击率 (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 允许系统自动调整出价并将预算转移给所属订单项，以优化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

 更新现有广告订单。