展示广告和Video 360 API v2 已停用。使用展示广告和Video 360 API v3。如需查看 v2 到 v3 的迁移说明，请参阅我们的迁移指南。

此页面由 Cloud Translation API 翻译。

REST Resource: advertisers.insertionOrders

资源：广告订单
- JSON 表示法
InsertionOrderType
KPI
- JSON 表示法
KpiType
InsertionOrderBudget
- JSON 表示法
InsertionOrderAutomationType
InsertionOrderBudgetSegment
- JSON 表示法
OptimizationObjective
方法

资源：广告订单

单个广告订单。

JSON 表示法

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,
  "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)` 必需。广告订单的预算支出速度设置。警告：自 2024 年 11 月 5 日起，`pacingType` `PACING_TYPE_ASAP` 将不再与 `pacingPeriod` `PACING_PERIOD_FLIGHT` 兼容。详细了解这项已公布的更改。
`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 表示法

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),
  "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)` 必需。预算期列表。您可以使用预算期为广告订单的指定时间段内指定具体预算。

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`	更新现有广告订单。

REST Resource: advertisers.insertionOrders

资源：广告订单

InsertionOrderType

KPI

KpiType

InsertionOrderBudget

InsertionOrderAutomationType

InsertionOrderBudgetSegment

OptimizationObjective

方法

`create`

`delete`

`get`

`list`

`listAssignedTargetingOptions`

`patch`