REST Resource: advertisers.lineItems

資源：LineItem

單一委刊項。

JSON 表示法 
{
  "name": string,
  "advertiserId": string,
  "campaignId": string,
  "insertionOrderId": string,
  "lineItemId": string,
  "displayName": string,
  "lineItemType": enum (LineItemType),
  "entityStatus": enum (EntityStatus),
  "updateTime": string,
  "partnerCosts": [
    {
      object (PartnerCost)
    }
  ],
  "flight": {
    object (LineItemFlight)
  },
  "budget": {
    object (LineItemBudget)
  },
  "pacing": {
    object (Pacing)
  },
  "frequencyCap": {
    object (FrequencyCap)
  },
  "partnerRevenueModel": {
    object (PartnerRevenueModel)
  },
  "conversionCounting": {
    object (ConversionCountingConfig)
  },
  "creativeIds": [
    string
  ],
  "bidStrategy": {
    object (BiddingStrategy)
  },
  "integrationDetails": {
    object (IntegrationDetails)
  },
  "inventorySourceIds": [
    string
  ],
  "targetingExpansion": {
    object (TargetingExpansionConfig)
  },
  "warningMessages": [
    enum (LineItemWarningMessage)
  ],
  "mobileApp": {
    object (MobileApp)
  },
  "reservationType": enum (ReservationType),
  "excludeNewExchanges": boolean
}
欄位
name

string

僅供輸出。委刊項的資源名稱。
advertiserId

string (int64 format)

僅供輸出。委刊項所屬的廣告主專屬 ID。
campaignId

string (int64 format)

僅供輸出。委刊項所屬的廣告活動專屬 ID。
insertionOrderId

string (int64 format)

必要欄位。無法變更。委刊項所屬的廣告訂單專屬 ID。
lineItemId

string (int64 format)

僅供輸出。委刊項的專屬 ID。由系統指派。
displayName

string

必要欄位。委刊項的顯示名稱。

必須採用 UTF-8 編碼，且大小不得超過 240 個位元組。
lineItemType

enum (LineItemType)

必要欄位。無法變更。委刊項類型。
entityStatus

enum (EntityStatus)

必要欄位。控制委刊項是否能支出預算並對廣告空間出價。

  • lineItems.create 方法只允許使用 ENTITY_STATUS_DRAFT。如要啟用委刊項，請使用 lineItems.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)

與委刊項相關的夥伴費用。

如果 lineItems.create 方法中沒有或留空，新建的委刊項會沿用上層廣告訂單的夥伴費用。
flight

object (LineItemFlight)

必要欄位。委刊項檔期的開始和結束時間。
budget

object (LineItemBudget)

必要欄位。委刊項的預算分配設定。
pacing

object (Pacing)

必要欄位。委刊項的預算支出速度設定。
frequencyCap

object (FrequencyCap)

必要欄位。委刊項的曝光展示頻率上限設定。

如要指派限制上限，則必須使用此設定物件中的 maxImpressions 欄位。
partnerRevenueModel

object (PartnerRevenueModel)

必要欄位。委刊項的夥伴收益模式設定。
conversionCounting

object (ConversionCountingConfig)

委刊項的轉換追蹤設定。
creativeIds[]

string (int64 format)

與委刊項相關聯的廣告素材 ID。
bidStrategy

object (BiddingStrategy)

必要欄位。委刊項的出價策略。
integrationDetails

object (IntegrationDetails)

委刊項的整合詳細資料。
inventorySourceIds[]

string (int64 format)

指派給委刊項的私人廣告空間來源 ID。
targetingExpansion

object (TargetingExpansionConfig)

委刊項的最佳化指定目標對象設定。

這項設定僅適用於使用自動出價且指定符合資格的目標對象名單的多媒體、影片或音訊委刊項。
warningMessages[]

enum (LineItemWarningMessage)

僅供輸出。委刊項產生的警告訊息。這些警告不會禁止儲存委刊項，但有些警告可能會禁止委刊項放送。
mobileApp

object (MobileApp)

委刊項宣傳的行動應用程式。

僅適用於 lineItemType 為 LINE_ITEM_TYPE_DISPLAY_MOBILE_APP_INSTALL 或 LINE_ITEM_TYPE_VIDEO_MOBILE_APP_INSTALL 時。
reservationType

enum (ReservationType)

僅供輸出。委刊項的預訂類型。
excludeNewExchanges

boolean

是否禁止新廣告交易平台由委刊項自動指定。這個欄位預設為 false。

LineItemType

可能的委刊項類型。

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

列舉
LINE_ITEM_TYPE_UNSPECIFIED

未指定類型值，或這個版本中的類型值不明。

這種類型的委刊項及其指定目標無法使用 API 建立或更新。
LINE_ITEM_TYPE_DISPLAY_DEFAULT 圖片、HTML5、原生或互動式多媒體廣告。
LINE_ITEM_TYPE_DISPLAY_MOBILE_APP_INSTALL 多媒體廣告可提高應用程式安裝量。
LINE_ITEM_TYPE_VIDEO_DEFAULT 在多種環境中以千次曝光出價為依據銷售的影片廣告。
LINE_ITEM_TYPE_VIDEO_MOBILE_APP_INSTALL 促成應用程式安裝的影片廣告。
LINE_ITEM_TYPE_DISPLAY_MOBILE_APP_INVENTORY

在行動應用程式廣告空間上放送的多媒體廣告。

這種類型的委刊項及其指定目標無法使用 API 建立或更新。
LINE_ITEM_TYPE_VIDEO_MOBILE_APP_INVENTORY

在行動應用程式廣告空間上放送的影片廣告。

這種類型的委刊項及其指定目標無法使用 API 建立或更新。
LINE_ITEM_TYPE_AUDIO_DEFAULT 即時出價音訊廣告可在多種環境中銷售。
LINE_ITEM_TYPE_VIDEO_OVER_THE_TOP OTT 廣告訂單中的 over-the-top 廣告。這個類型僅適用於廣告訂單為 insertionOrderType OVER_THE_TOP 的委刊項。

LineItemFlight

控制委刊項有效時間長度的設定。

JSON 表示法 
{
  "flightDateType": enum (LineItemFlightDateType),
  "dateRange": {
    object (DateRange)
  },
  "triggerId": string
}
欄位
flightDateType

enum (LineItemFlightDateType)

必要欄位。委刊項的檔期類型。
dateRange

object (DateRange)

委刊項的檔期開始和結束日期。然後以上層廣告客戶的時區相對解析。

  • 當 flightDateType 為 LINE_ITEM_FLIGHT_DATE_TYPE_CUSTOM 時必須提供。僅限輸出。
  • 建立新檔期時，startDate 和 endDate 都必須是未來的時間。
  • 過去帶有 startDate 的航班，包含可變動的 endDate，但 startDate 不可變動。
  • 「endDate」必須是在 2037 年前的 startDate 以上版本。
triggerId

string (int64 format)

與委刊項相關聯的手動觸發條件 ID。

  • 當 flightDateType 為 LINE_ITEM_FLIGHT_DATE_TYPE_TRIGGER 時必須提供。除非另有設定，否則請勿設定。
  • 設定完成後，委刊項的檔期會沿用上層廣告訂單的日期。
  • 所選觸發條件在上層廣告訂單的檔期內啟用後，有效委刊項就會支出預算。

警告：使用手動觸發條件的委刊項將不再於 Display & Video 360 放送。這個欄位將於 2023 年 8 月 1 日停用。詳情請參閱功能淘汰公告。

LineItemFlightDateType

委刊項的檔期類型。

列舉
LINE_ITEM_FLIGHT_DATE_TYPE_UNSPECIFIED 未指定類型值，或這個版本中的類型值不明。
LINE_ITEM_FLIGHT_DATE_TYPE_INHERITED 委刊項的檔期會沿用上層廣告訂單的日期。
LINE_ITEM_FLIGHT_DATE_TYPE_CUSTOM 委刊項使用的是專屬的自訂檔期。
LINE_ITEM_FLIGHT_DATE_TYPE_TRIGGER

委刊項使用觸發條件。

警告：使用手動觸發條件的委刊項將不再於 Display & Video 360 放送。這個值將於 2023 年 8 月 1 日停用。詳情請參閱功能淘汰公告。

LineItemBudget

控制預算分配方式的設定。

JSON 表示法 
{
  "budgetAllocationType": enum (LineItemBudgetAllocationType),
  "budgetUnit": enum (BudgetUnit),
  "maxAmount": string
}
欄位
budgetAllocationType

enum (LineItemBudgetAllocationType)

必要欄位。預算分配的類型。

只有在上層廣告訂單啟用自動預算分配功能時，才能使用「LINE_ITEM_BUDGET_ALLOCATION_TYPE_AUTOMATIC」。
budgetUnit

enum (BudgetUnit)

僅供輸出。預算單位會指定預算是以貨幣或曝光為依據。這個值會沿用父項廣告訂單的值。
maxAmount

string (int64 format)

委刊項將支出的最高預算金額。必須大於 0。

當 budgetAllocationType 為：

  • LINE_ITEM_BUDGET_ALLOCATION_TYPE_AUTOMATIC，這個欄位由系統設定，不可變動。
  • LINE_ITEM_BUDGET_ALLOCATION_TYPE_FIXED (如果 budgetUnit 為：
    • BUDGET_UNIT_CURRENCY，這個欄位代表支出的最高預算金額 (以廣告主貨幣的百萬分之一表示)。舉例來說，1500000 代表 1.5 標準貨幣單位。
    • BUDGET_UNIT_IMPRESSIONS，這個欄位代表要放送的曝光次數上限。
  • LINE_ITEM_BUDGET_ALLOCATION_TYPE_UNLIMITED，這個欄位不適用，系統將忽略這個欄位。

LineItemBudgetAllocationType

預算分配方式可能的類型。

列舉
LINE_ITEM_BUDGET_ALLOCATION_TYPE_UNSPECIFIED 未指定類型值，或這個版本中的類型值不明。
LINE_ITEM_BUDGET_ALLOCATION_TYPE_AUTOMATIC 委刊項已啟用自動預算分配功能。
LINE_ITEM_BUDGET_ALLOCATION_TYPE_FIXED 系統會為委刊項分配固定的預算金額上限。
LINE_ITEM_BUDGET_ALLOCATION_TYPE_UNLIMITED 委刊項未套用任何預算限制。

PartnerRevenueModel

控制夥伴收益計算方式的設定。

JSON 表示法 
{
  "markupType": enum (PartnerRevenueModelMarkupType),
  "markupAmount": string
}
欄位
markupType

enum (PartnerRevenueModelMarkupType)

必要欄位。夥伴收益模式的標記類型。
markupAmount

string (int64 format)

必要欄位。夥伴收益模式的加價金額。不得小於 0。

  • 當 markupType 設為 PARTNER_REVENUE_MODEL_MARKUP_TYPE_CPM 時，這個欄位會以廣告客戶幣別的百萬分之一表示千次曝光出價加成。舉例來說，1500000 代表 1.5 標準貨幣單位。
  • 當 markupType 設為 PARTNER_REVENUE_MODEL_MARKUP_TYPE_MEDIA_COST_MARKUP 時，這個欄位代表以毫秒為單位的媒體費用百分比加成。例如，100 代表 0.1% (十進位數字 0.001)。
  • 如果 markupType 設為 PARTNER_REVENUE_MODEL_MARKUP_TYPE_TOTAL_MEDIA_COST_MARKUP，這個欄位代表媒體費用總額百分比加成 (以毫秒為單位)。例如，100 代表 0.1% (十進位數字 0.001)。

PartnerRevenueModelMarkupType

夥伴收益模式可能適用的標記類型。

列舉
PARTNER_REVENUE_MODEL_MARKUP_TYPE_UNSPECIFIED 未指定類型值，或這個版本中的類型值不明。
PARTNER_REVENUE_MODEL_MARKUP_TYPE_CPM 根據固定千次曝光出價計算夥伴收益。
PARTNER_REVENUE_MODEL_MARKUP_TYPE_MEDIA_COST_MARKUP

依據媒體費用的特定百分比附加費用計算夥伴收益。
PARTNER_REVENUE_MODEL_MARKUP_TYPE_TOTAL_MEDIA_COST_MARKUP 根據媒體費用總額附加百分比 (包含所有夥伴費用和資料費用) 計算夥伴收益。

ConversionCountingConfig

控制轉換計算方式的設定。

所有點擊後轉換都會列入計算。您可以設定瀏覽後轉換計數的百分比值。

JSON 表示法 
{
  "postViewCountPercentageMillis": string,
  "floodlightActivityConfigs": [
    {
      object (TrackingFloodlightActivityConfig)
    }
  ]
}
欄位
postViewCountPercentageMillis

string (int64 format)

要計入的瀏覽後轉換次數百分比，以千分之一為單位 (1/1000 的百分比)。必須介於 0 到 100000 (含) 之間。

舉例來說，如要追蹤 50% 的點擊後轉換，請將值設為 50000。
floodlightActivityConfigs[]

object (TrackingFloodlightActivityConfig)

用於追蹤轉換的 Floodlight 活動設定。

計算的轉換次數是這個欄位中指定的所有 Floodlight 活動 ID 帶來的所有轉換總和。

TrackingFloodlightActivityConfig

控管單一 Floodlight 活動設定行為的設定。

JSON 表示法 
{
  "floodlightActivityId": string,
  "postClickLookbackWindowDays": integer,
  "postViewLookbackWindowDays": integer
}
欄位
floodlightActivityId

string (int64 format)

必要欄位。Floodlight 活動的 ID。
postClickLookbackWindowDays

integer

必要欄位。廣告獲得點擊後可計入轉換的天數。必須介於 0 到 90 (含) 之間。
postViewLookbackWindowDays

integer

必要欄位。系統可能會在使用者觀看廣告後計入轉換的天數。必須介於 0 到 90 (含) 之間。

TargetingExpansionConfig

可控制委刊項的最佳化指定目標對象設定的設定。

JSON 表示法 
{
  "targetingExpansionLevel": enum (TargetingExpansionLevel),
  "excludeFirstPartyAudience": boolean
}
欄位
targetingExpansionLevel

enum (TargetingExpansionLevel)

必要欄位。是否啟用最佳化指定目標對像功能。

這個欄位支援下列值：

  • NO_EXPANSION：已停用最佳化指定目標對像功能
  • LEAST_EXPANSION：已啟用最佳化指定目標對像功能

如果將這個欄位設為任何其他值，則會自動設為 LEAST_EXPANSION。

該欄位將使用 NO_EXPANSION 做為預設值，如果您未設定該欄位，系統會自動指派值。
excludeFirstPartyAudience
(deprecated)

boolean

是否要在擴展指定目標中排除第一方目標對象。

這個欄位已隨著最佳化指定目標對象功能推出。

這個欄位會設為 false。如果這個欄位在已淘汰時設為 true，則指派給這個委刊項的所有正面第一方指定目標對象將替換成相同第一方目標對象的排除指定目標，以確保繼續排除這些目標對象。

TargetingExpansionLevel

最佳化指定目標對象設定。

列舉
TARGETING_EXPANSION_LEVEL_UNSPECIFIED 未指定最佳化指定目標對象設定，或這個版本中不明。
NO_EXPANSION 最佳化指定目標對像已關閉。
LEAST_EXPANSION 最佳化指定目標對像已開啟。
SOME_EXPANSION

如已使用，會自動設為 LEAST_EXPANSION。
BALANCED_EXPANSION

如已使用，會自動設為 LEAST_EXPANSION。
MORE_EXPANSION

如已使用，會自動設為 LEAST_EXPANSION。
MOST_EXPANSION

如已使用，會自動設為 LEAST_EXPANSION。

LineItemWarningMessage

委刊項產生的警告訊息。這些類型的警告不會禁止儲存委刊項，但可能會使委刊項無法放送。

列舉
LINE_ITEM_WARNING_MESSAGE_UNSPECIFIED 未指定或不明。
INVALID_FLIGHT_DATES 這個委刊項的檔期無效。委刊項將不會放送。
EXPIRED 這個委刊項的結束日期是過去的日期。
PENDING_FLIGHT 這個委刊項日後會開始放送。
ALL_PARTNER_ENABLED_EXCHANGES_NEGATIVELY_TARGETED 所有合作夥伴啟用的廣告交易平台都已遭到排除指定。委刊項將不會放送。
INVALID_INVENTORY_SOURCE 未指定任何有效廣告空間來源。委刊項將不會放送。
APP_INVENTORY_INVALID_SITE_TARGETING 這個委刊項的應用程式和網址指定目標不包含任何行動應用程式。這種委刊項類型需要將行動應用程式納入管道、網站清單或應用程式指定目標中。委刊項將不會放送。
APP_INVENTORY_INVALID_AUDIENCE_LISTS 這個委刊項沒有指定任何行動裝置使用者。這個委刊項類型會要求您指定包含行動裝置使用者的使用者名單。委刊項將不會放送。
NO_VALID_CREATIVE 這個委刊項未包含任何有效的廣告素材。委刊項將不會放送。
PARENT_INSERTION_ORDER_PAUSED 這個委刊項的廣告訂單已暫停。委刊項將不會放送。
PARENT_INSERTION_ORDER_EXPIRED 這個委刊項的廣告訂單結束日期設在過去。委刊項將不會放送。
NO_POSITIVE_AUDIENCE_LIST_TARGETED 這個委刊項並未指定任何目標對象名單，這可能會導致預算的支出速度過快。
APP_INSTALL_NO_CONVERSION_PIXEL 這個應用程式安裝委刊項未設定任何轉換像素。
TARGETING_REVOKED_OR_CLOSED_USER_LIST 這個委刊項指定一或多份已經不再提供的使用者名單。日後，委刊項會停止放送，因此建議您從指定目標中移除這些名單。
APP_INSTALL_NO_OPTIMAL_BIDDING_STRATEGY 這個應用程式安裝委刊項沒有最佳出價策略。
CREATIVE_SIZE_NOT_IN_USE_FOR_TARGETED_DEALS 這個委刊項指定的交易可接受未使用的廣告素材大小。這可能會限制委刊項的放送或成效。
NO_CREATIVE_FOR_TARGETED_DEALS 這個委刊項不含任何指定交易的廣告素材。
TARGETING_DEPRECATED_GEO_TARGET 這個委刊項指定的指定地理區域已經淘汰。
DEPRECATED_FIRST_PARTY_AUDIENCE_EXCLUSION

這個委刊項使用了已淘汰的 excludeFirstPartyAudience 設定，並已排定在 2023 年 3 月 25 日後停用。

請更新 API 整合，在 2023 年 3 月 25 日前直接排除任何使用指定目標對象的第一方目標對象，因應「excludeFirstPartyAudience」欄位即將停用。

MobileApp

由行動應用程式安裝委刊項宣傳的行動應用程式。

JSON 表示法 
{
  "appId": string,
  "platform": enum (Platform),
  "displayName": string,
  "publisher": string
}
欄位
appId

string

必要欄位。平台商店提供的應用程式 ID。

Android 應用程式是以 Android Play 商店使用的軟體包 ID 識別，例如 com.google.android.gm。

iOS 應用程式是由 Apple App Store 使用的 9 位數應用程式 ID 識別，例如 422689480。
platform

enum (Platform)

僅供輸出。應用程式平台。
displayName

string

僅供輸出。應用程式名稱。
publisher

string

僅供輸出。應用程式發布商。

平台

可能的行動應用程式平台。

列舉
PLATFORM_UNSPECIFIED 未指定平台。
IOS iOS 平台。
ANDROID Android 平台。

方法

bulkEditLineItemAssignedTargetingOptions

 單一委刊項底下的大量編輯指定目標選項。

bulkListLineItemAssignedTargetingOptions

 列出跨指定類型委刊項的指派指定目標選項。

create

 建立新委刊項。

delete

 刪除委刊項。

generateDefault

 建立新委刊項，其中包含沿用廣告訂單和 ENTITY_STATUS_DRAFT entity_status 的設定 (包括指定目標)。

get

 取得委刊項。

list

 列出廣告客戶中的委刊項。

patch

 更新現有的委刊項。