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 世界协调时间（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 时为必填项。其他情况则不得设置。
  • 设置后，该订单项的排期会沿用其父级广告订单的排期。
  • 如果在父级广告订单的排期内启用了所选触发器，有效订单项便会产生支出。

警告：使用手动触发器的订单项不再在展示广告网络中投放，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

订单项使用了触发器。

警告：使用手动触发器的订单项不再在展示广告网络中投放，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 为）： <ph type="x-smartling-placeholder">
      </ph>
    • 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 到 100000 之间（含 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 之间（含 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

 更新现有订单项。