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)
  },
  "performanceGoal": {
    object (PerformanceGoal)
  },
  "budget": {
    object (InsertionOrderBudget)
  },
  "bidStrategy": {
    object (BiddingStrategy)
  },
  "reservationType": enum (ReservationType),
  "billableOutcome": enum (BillableOutcome)
}
字段
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)

广告订单的其他集成详情。

performanceGoal

object (PerformanceGoal)

必需。广告订单的效果目标。

budget

object (InsertionOrderBudget)

必需。广告订单的预算分配设置。

bidStrategy

object (BiddingStrategy)

广告订单的出价策略。默认情况下,系统会设置 fixedBid

reservationType

enum (ReservationType)

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

billableOutcome

enum (BillableOutcome)

不可变。广告订单的可结算结果。

“按结果付费购买”模式已被弃用。BILLABLE_OUTCOME_PAY_PER_IMPRESSION 是唯一的有效值。

InsertionOrderType

可能的广告订单类型。

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

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

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 自动分配预算。允许系统将预算自动转移给自有订单项,以优化performanceGoal指定的效果。未对出价设置执行自动化操作。
INSERTION_ORDER_AUTOMATION_TYPE_NONE 未在广告订单级别自动设置出价或预算。出价和预算必须在订单项级别手动配置。
INSERTION_ORDER_AUTOMATION_TYPE_BID_BUDGET 允许系统自动调整出价并将预算转移给所属订单项,以优化performanceGoal定义的效果。

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)

必需。预算期的开始日期和结束日期设置。它们会根据父级广告客户的时区进行解析。

  • 创建新的预算期时,startDateendDate 都必须是将来的时间。
  • 某个过去具有 startDate 的现有预算期的 endDate 可变,但 startDate 不可变。
  • endDate 必须是 startDate 或更晚日期,并且二者均早于 2037 年。
campaignBudgetId

string (int64 format)

此广告订单预算期所属的广告系列预算的 budgetId

BillableOutcome

广告订单可能的可结算结果。

枚举
BILLABLE_OUTCOME_UNSPECIFIED 未指定的计费结果。
BILLABLE_OUTCOME_PAY_PER_IMPRESSION 按展示次数付费。
BILLABLE_OUTCOME_PAY_PER_CLICK

按点击付费。

BILLABLE_OUTCOME_PAY_PER_VIEWABLE_IMPRESSION

按 Active View 付费。

方法

bulkListInsertionOrderAssignedTargetingOptions

列出为广告订单的各个定位类型分配的定位选项。

create

创建新的广告订单。

delete

删除广告订单。

get

获取广告订单。

list

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

patch

更新现有广告订单。