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)
}
字段
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)

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

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。

方法

create

 创建新的广告订单。

delete

 删除广告订单。

get

 获取广告订单。

list

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

listAssignedTargetingOptions

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

patch

 更新现有广告订单。