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),
  "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)

必要欄位。廣告訂單的預算支出速度設定。

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 表示法
{
  "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_typekpi_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 個字元。

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

必要欄位。預算區隔清單。使用預算區隔來指定廣告訂單放送期間內的特定預算。

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

更新現有的廣告訂單。