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)。

这被称为“目标”和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_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

 更新现有广告订单。