REST Resource: advertisers.lineItems

资源：订单项

单个订单项。

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 世界协调时间 (UTC)（即“祖鲁时”）格式，具有纳秒级分辨率，最多包含九个小数位。示例："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 在各种环境中均按 CPM 出售的视频广告。
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 广告订单中的 OTT 服务广告。此类型仅适用于广告订单为“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 必须为 startDate 或更晚，并且两者都必须在 2037 年之前。
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 根据固定 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 到 100,000 之间（含 0 和 100,000）。

例如，要跟踪 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 之间（含 0 和 90）。
postViewLookbackWindowDays

integer

必需。系统在用户观看广告后可能统计转化的天数。必须介于 0 和 90 之间（含 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 日之后停用。

请在 2023 年 3 月 25 日之前更新您的 API 集成，直接排除使用受众群体定位的所有第一方受众群体，以配合 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

 更新现有订单项。