REST Resource: advertisers.insertionOrders

資源：InsertOrder

單一廣告訂單。

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 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度和最多九個小數位數。範例："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 Over-the-top。

主要成效指標

控制廣告訂單主要成效指標 (或稱 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 是單次操作出價 (單次操作出價)。
KPI_TYPE_CTR KPI 是點閱率 (CTR) 百分比。
KPI_TYPE_VIEWABILITY KPI 是可視度百分比。
KPI_TYPE_CPIAVC KPI 是單次有聲播放且完整播放的單次曝光出價。
KPI_TYPE_CPE KPI 是單次參與出價 (單次參與出價)。
KPI_TYPE_CPV KPI 設為單次收視出價。
KPI_TYPE_CLICK_CVR 主要成效指標是指點擊轉換率 (單次點擊轉換) 百分比。
KPI_TYPE_IMPRESSION_CVR 主要成效指標是指曝光轉換率 (單次曝光轉換次數) 百分比。
KPI_TYPE_VCPM KPI 是千次可視曝光出價。
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 必須是 2037 年前的 startDate 或以後的日期。
campaignBudgetId

string (int64 format)

這個廣告訂單預算區隔所屬的廣告活動預算 budgetId。

方法

create

 建立新的廣告訂單。

delete

 刪除廣告訂單。

get

 取得廣告訂單。

list

 列出廣告客戶的廣告訂單。

listAssignedTargetingOptions

 列出廣告訂單在不同指定目標類型的指定目標選項。

patch

 更新現有的廣告訂單。