REST Resource: advertisers.insertionOrders

資源：InsertionOrder

單一廣告訂單。

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 (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)

僅供輸出。上次更新插入單的時間戳記。由系統指派。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
partnerCosts[]

object (PartnerCost)

(選用步驟) 與廣告訂單相關的合作夥伴費用。

如果 insertionOrders.create 方法中沒有或空白，新建立的廣告訂單會沿用合作夥伴設定中的合作夥伴費用。
pacing

object (Pacing)

必填。廣告訂單的預算支出速度設定。

「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。

如果將 budget 欄位 automationType 設為 INSERTION_ORDER_AUTOMATION_TYPE_BUDGET 或 INSERTION_ORDER_AUTOMATION_TYPE_BID_BUDGET，廣告訂單就會對委刊項採用這項出價策略。如果強制執行的出價策略與委刊項的enableOptimizedTargeting設定不相容，系統會更新最佳化指定目標對象設定。
reservationType

enum (ReservationType)

僅供輸出。廣告訂單的預訂類型。
optimizationObjective

enum (OptimizationObjective)

必填。廣告訂單的最佳化目標。

InsertionOrderType

廣告訂單的可能類型。

廣告訂單類型會決定適用的設定和選項，例如廣告格式或指定目標選項。

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

主要成效指標

控制廣告訂單主要成效指標 (簡稱 KPI) 的設定。

JSON 表示法 
{
  "kpiType": enum (KpiType),
  "kpiAlgorithmId": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "kpiAmountMicros": string,
  "kpiPercentageMicros": string,
  "kpiString": string
  // End of mutually exclusive fields.
}
欄位
kpiType

enum (KpiType)

必填。KPI 類型。
kpiAlgorithmId

string (int64 format)

(選用步驟) 與 KPI_CUSTOM_IMPRESSION_VALUE_OVER_COST 相關聯的自訂出價演算法 ID。如未選取適當的 KPI，系統會忽略這個欄位。
必填。KPI 的值。相關欄位對應至 kpi_type。以下列出互斥欄位。回應中最多會設定一個欄位：
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_TYPE_CPC 關鍵指標為單次點擊出價 (CPC)。
KPI_TYPE_CPA 關鍵指標為單次動作出價 (CPA)。
KPI_TYPE_CTR 關鍵指標是點閱率百分比。
KPI_TYPE_VIEWABILITY KPI 為可視度百分比。
KPI_TYPE_CPIAVC 關鍵指標為 CPIAVC (單次有聲可見完整播放的曝光出價)。
KPI_TYPE_CPE 關鍵指標為 CPE (單次參與出價)。
KPI_TYPE_CPV KPI 設定為單次收視出價。
KPI_TYPE_CLICK_CVR 關鍵指標為點擊轉換率 (單次點擊轉換次數) 百分比。
KPI_TYPE_IMPRESSION_CVR 關鍵指標是曝光轉換率 (每次曝光的轉換次數) 百分比。
KPI_TYPE_VCPM 關鍵指標為千次可視曝光出價 (每千次可視曝光的費用)。
KPI_TYPE_VTR 這項 KPI 是指 YouTube 觀看率 (每次曝光的 YouTube 觀看次數) 百分比。
KPI_TYPE_AUDIO_COMPLETION_RATE 關鍵指標為音訊播放完成率 (每次曝光的音訊完整播放次數) 百分比。
KPI_TYPE_VIDEO_COMPLETION_RATE 關鍵指標是影片播放完成率 (每次曝光的完整影片觀看次數) 百分比。
KPI_TYPE_CPCL KPI 是以 CPCL (單次完整音訊播放費用) 設定。
KPI_TYPE_CPCV 並以 CPCV (單次完整收視出價) 做為 KPI。
KPI_TYPE_TOS10 這項 KPI 是以畫面顯示時間超過 10 秒的比率為準 (畫面顯示時間超過 10 秒的可評估不可略過曝光次數百分比)。
KPI_TYPE_MAXIMIZE_PACING 系統會優先將預算用完，同時盡量提升品牌影響力。
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 允許系統自動調整出價，並將預算轉移至自有委刊項，以最佳化 bidStrategy 定義的成效。

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 都必須設於未來。
  • 過去的現有預算區隔具有可變動的 endDate，但 startDate 不變。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

 列出廣告主中的廣告訂單。

patch

 更新現有廣告訂單。