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_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

 更新现有广告订单。