多媒體和Video 360 API v2 即將停用。使用多媒體和Video 360 API v3。如需 v2 到 v3 的遷移操作說明，請參閱我們的遷移指南。

本頁面由 Cloud Translation API 翻譯而成。

REST Resource: advertisers.insertionOrders

資源：InsertOrder
- JSON 表示法
InsertionOrderType
KPI
- JSON 表示法
KpiType
InsertionOrderBudget
- JSON 表示法
InsertionOrderAutomationType
InsertionOrderBudgetSegment
- JSON 表示法
最佳化目標
方法

資源：InsertOrder

單一廣告訂單。

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 世界標準時間「Zulu」的時間戳記格式，解析度不超過奈秒，最多 9 個小數位數。範例：`"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)。這項目標稱為「目標」多媒體和Video 360 介面。
`budget`	`object (InsertionOrderBudget)` 必要欄位。廣告訂單的預算分配設定。
`bidStrategy`	`object (BiddingStrategy)` 廣告訂單的出價策略。根據預設，系統會設定 `fixedBid`。
`reservationType`	`enum (ReservationType)` 僅供輸出。廣告訂單的預訂類型。
`optimizationObjective`	`enum (OptimizationObjective)` 選用設定。廣告訂單的最佳化目標。這個欄位僅適用於許可清單中的客戶。如果客戶未列入許可清單，這個欄位會為空值，嘗試設定時會傳回錯誤。

InsertionOrderType

可能的廣告訂單類型。

廣告訂單的類型會決定您可以使用的設定和選項，例如廣告或指定目標選項。

列舉
`INSERTION_ORDER_TYPE_UNSPECIFIED`	未指定廣告訂單類型或類型不明。
`RTB`	即時出價。
`OVER_THE_TOP`	over-the-top。

主要成效指標

控管廣告訂單主要成效指標 (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 為千次曝光出價。
`KPI_TYPE_CPC`	KPI 是單次點擊出價。
`KPI_TYPE_CPA`	KPI 為單次操作出價 (CPA)，
`KPI_TYPE_CTR`	KPI 是點閱率百分比。
`KPI_TYPE_VIEWABILITY`	KPI 是可視度百分比
`KPI_TYPE_CPIAVC`	KPI 是單次有聲可視完整播放的曝光出價 (每次有聲可視曝光所需的費用)。
`KPI_TYPE_CPE`	KPI 是單次參與出價。
`KPI_TYPE_CPV`	KPI 是以單次收視出價 (單次收視出價) 為依據。
`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` 必須是 2037 年之前的 `startDate`。
`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

資源：InsertOrder

InsertionOrderType

主要成效指標

KpiType

InsertionOrderBudget

InsertionOrderAutomationType

InsertionOrderBudgetSegment

OptimizationObjective

方法

`create`

`delete`

`get`

`list`

`listAssignedTargetingOptions`

`patch`