本指南阐述了提案订单项的定义，并逐步介绍了如何通过 API 创建 ProposalLineItem 对象。此外，本指南还介绍了必填字段，并探讨了当您在 Proposal 对象下创建提案订单项后可执行的后续步骤。
基础入门
什么是提案订单项？在 DFP 销售管理系统界面中，您会看到 Product 对象的目录，这些对象代表允许使用的定义或预设定义的通用模板，以方便定位。这些对象已经与 RateCard 对象配对，后者允许将 PremiumRate 对象应用于定价。当您填充其他必填的结算字段和投放字段时，您实际上是在创建 ProposalLineItem 对象（嵌套在 Proposal 对象下），代表 DFP 广告管理系统（以下简称 DFP）内尚未进入广告投放管理阶段的订单项对象。
通过 API 创建提案订单项
要在 API 中创建提案订单项，您必须拥有以下对象：
- 作为此提案订单项的关联对象的
Proposal - 作为此提案订单项的定价依据的
RateCard - 作为基础的
Product
请先在本地创建一个 ProposalLineItem 对象并为其分配名称。
Java
// Get the ProposalLineItemService.
ProposalLineItemServiceInterface proposalLineItemService =
dfpServices.get(session, ProposalLineItemServiceInterface.class);
// Create a proposal line item.
ProposalLineItem proposalLineItem = new ProposalLineItem();
proposalLineItem.setName("Proposal line item #" + new Random().nextInt(Integer.MAX_VALUE));
Python
# Initialize appropriate service.
proposal_line_item_service = client.GetService(
'ProposalLineItemService', version='v201711')
# Create a single proposal line item.
proposal_line_item = {
'name': 'Proposal line item #%s' % uuid.uuid4(),
...
PHP
$proposalLineItemService = $dfpServices->get($session, ProposalLineItemService::class);
// Create a standard proposal line item.
$proposalLineItem = new ProposalLineItem();
$proposalLineItem->setName('Proposal line item #' . uniqid());
$proposalLineItem->setLineItemType(LineItemType::STANDARD);
C#
using (ProposalLineItemService proposalLineItemService =
(ProposalLineItemService) user.GetService(DfpService.v201711.ProposalLineItemService))
// Create a proposal line item.
ProposalLineItem proposalLineItem = new ProposalLineItem();
proposalLineItem.name = "Proposal line item #" + new Random().Next(int.MaxValue);
在本地创建此提案订单项后，您便可以将其与您的提案相关联，并分别设置沿用其定位和定价的产品和价目表。
Java
proposalLineItem.setProposalId(proposalId);
proposalLineItem.setRateCardId(rateCardId);
proposalLineItem.setProductId(productId);
proposalLineItem.setTargeting(targeting);
Python
...
'rateCardId': rate_card_id,
'productId': product_id,
'proposalId': proposal_id,
...
PHP
$proposalLineItem->setProposalId($proposalId);
$proposalLineItem->setRateCardId($rateCardId);
$proposalLineItem->setProductId($productId);
C#
proposalLineItem.proposalId = proposalId;
proposalLineItem.rateCardId = rateCardId;
proposalLineItem.productId = productId;
proposalLineItem.targeting = targeting;
提案订单项支持定位字段，其方式与 LineItem 对象一样。同样，提案订单项也需要至少 1 个 InventoryTargeting 对象。在这种情况下，网络随机广告 (RON) 提案订单项会通过定位相应广告联盟的根广告单元的方式进行创建。
Java
// Get the NetworkService.
NetworkServiceInterface networkService =
dfpServices.get(session, NetworkServiceInterface.class);
// Get the root ad unit ID used to target the whole site.
String rootAdUnitId = networkService.getCurrentNetwork().getEffectiveRootAdUnitId();
// Create inventory targeting.
InventoryTargeting inventoryTargeting = new InventoryTargeting();
// Create ad unit targeting for the root ad unit (i.e. the whole network).
AdUnitTargeting adUnitTargeting = new AdUnitTargeting();
adUnitTargeting.setAdUnitId(rootAdUnitId);
adUnitTargeting.setIncludeDescendants(true);
inventoryTargeting.setTargetedAdUnits(new AdUnitTargeting[] {adUnitTargeting});
// Create targeting.
Targeting targeting = new Targeting();
targeting.setInventoryTargeting(inventoryTargeting);
Python
...
'targeting': {
'inventoryTargeting': {
'targetedAdUnits': {
'adUnitId': root_ad_unit_id
}
}
},
...
PHP
// Create ad unit targeting for the root ad unit (i.e. the whole network).
$rootAdUnitId = $networkService->getCurrentNetwork()
->getEffectiveRootAdUnitId();
$inventoryTargeting = new InventoryTargeting();
$adUnitTargeting = new AdUnitTargeting();
$adUnitTargeting->setAdUnitId($rootAdUnitId);
$adUnitTargeting->setIncludeDescendants(true);
$inventoryTargeting->setTargetedAdUnits([$adUnitTargeting]);
$targeting = new Targeting();
$targeting->setInventoryTargeting($inventoryTargeting);
$proposalLineItem->setTargeting($targeting);
C#
// Get the root ad unit ID used to target the whole site.
String rootAdUnitId = networkService.getCurrentNetwork().effectiveRootAdUnitId;
// Create inventory targeting.
InventoryTargeting inventoryTargeting = new InventoryTargeting();
// Create ad unit targeting for the root ad unit (i.e. the whole network).
AdUnitTargeting adUnitTargeting = new AdUnitTargeting();
adUnitTargeting.adUnitId = rootAdUnitId;
adUnitTargeting.includeDescendants = true;
inventoryTargeting.targetedAdUnits = new AdUnitTargeting[] { adUnitTargeting };
// Create targeting.
Targeting targeting = new Targeting();
targeting.inventoryTargeting = inventoryTargeting;
添加所需的 InventoryTargeting 对象后，您就得为预期订单项指定投放开始日期和结束日期，并指定已为 Goal 对象设置的投放信息。
Java
// Set the length of the proposal line item to run.
proposalLineItem.setStartDateTime(DateTimes.toDateTime(Instant.now(), "America/New_York"));
proposalLineItem.setEndDateTime(
DateTimes.toDateTime(Instant.now().plus(Duration.standardDays(30L)), "America/New_York"));
// Set pricing for the proposal line item for 1000 impressions at a CPM of $2
// for a total value of $2.
Goal goal = new Goal();
goal.setUnits(1000L);
goal.setUnitType(UnitType.IMPRESSIONS);
proposalLineItem.setGoal(goal);
proposalLineItem.setNetCost(new Money("USD", 2000000L));
proposalLineItem.setNetRate(new Money("USD", 2000000L));
proposalLineItem.setRateType(RateType.CPM);
// Set delivery specifications for the proposal line item.
proposalLineItem.setDeliveryRateType(DeliveryRateType.EVENLY);
proposalLineItem.setCreativeRotationType(CreativeRotationType.OPTIMIZED);
Python
...
'startDateTime': start_datetime,
'endDateTime': end_datetime,
'goal': {
'units': '1000',
'unitType': 'IMPRESSIONS',
},
'netCost': {
'currencyCode': 'USD',
'microAmount': '2000000'
},
'netRate': {
'currencyCode': 'USD',
'microAmount': '2000000'
},
'rateType': 'CPM',
'deliveryRateType': 'EVENLY',
'creativeRotationType': 'OPTIMIZED',
...
PHP
// Set the length of the proposal line item to run.
$proposalLineItem->setStartDateTime(
DfpDateTimes::fromDateTime(
new DateTime('now', new DateTimeZone('America/New_York'))
)
);
$proposalLineItem->setEndDateTime(
DfpDateTimes::fromDateTime(
new DateTime('+1 month', new DateTimeZone('America/New_York'))
)
);
// Set pricing for the proposal line item for 1000 impressions at a CPM of
// $2 for a total value of $2.
$goal = new Goal();
$goal->setUnits(1000);
$goal->setUnitType(UnitType::IMPRESSIONS);
$proposalLineItem->setGoal($goal);
$proposalLineItem->setNetCost(new Money('USD', 2000000));
$proposalLineItem->setNetRate(new Money('USD', 2000000));
$proposalLineItem->setRateType(RateType::CPM);
// Set delivery specifications for the proposal line item.
$proposalLineItem->setDeliveryRateType(DeliveryRateType::EVENLY);
$proposalLineItem->setCreativeRotationType(CreativeRotationType::OPTIMIZED);
C#
// Set the length of the proposal line item to run.
proposalLineItem.startDateTime =
DateTimeUtilities.FromDateTime(System.DateTime.Now.AddDays(7), "America/New_York");
proposalLineItem.endDateTime =
DateTimeUtilities.FromDateTime(System.DateTime.Now.AddDays(30), "America/New_York");
// Set pricing for the proposal line item for 1000 impressions at a CPM of $2
// for a total value of $2.
proposalLineItem.goal = new Goal() { unitType = UnitType.IMPRESSIONS, units = 1000L };
proposalLineItem.netCost = new Money() { currencyCode = "USD", microAmount = 2000000L };
proposalLineItem.netRate = new Money() { currencyCode = "USD", microAmount = 2000000L };
proposalLineItem.rateType = RateType.CPM;
// Set delivery specifications for the proposal line item.
proposalLineItem.deliveryRateType = DeliveryRateType.EVENLY;
proposalLineItem.creativeRotationType = CreativeRotationType.OPTIMIZED;
您还可以替换提案订单项中从相应提案正常沿用的结算信息。您可以设置 Proposal 对象允许的相同 BillingCap、BillingSource 和 BillingSchedule 字段。
Java
// Set billing specifications for the proposal line item.
proposalLineItem.setBillingCap(BillingCap.CAPPED_CUMULATIVE);
proposalLineItem.setBillingSource(BillingSource.THIRD_PARTY_VOLUME);
Python
...
'billingCap': 'CAPPED_CUMULATIVE',
'billingSource': 'THIRD_PARTY_VOLUME',
...
PHP
// Set billing specifications for the proposal line item.
$proposalLineItem->setBillingCap(BillingCap::CAPPED_CUMULATIVE);
$proposalLineItem->setBillingSource(BillingSource::THIRD_PARTY_VOLUME);
C#
// Set billing specifications for the proposal line item.
proposalLineItem.billingCap = BillingCap.CAPPED_CUMULATIVE;
proposalLineItem.billingSource = BillingSource.THIRD_PARTY_VOLUME;
设置完这些字段后，您便可通过对 ProposalLineItem 对象的数组调用 createProposalLineItems 来新建提案订单项。
Java
// Create the proposal line item on the server.
ProposalLineItem[] proposalLineItems = proposalLineItemService.createProposalLineItems(
new ProposalLineItem[] {proposalLineItem});
Python
# Add proposal line items.
proposal_line_items = proposal_line_item_service.createProposalLineItems(
[proposal_line_item])
PHP
// Create the proposal line items on the server.
$results = $proposalLineItemService->createProposalLineItems([$proposalLineItem]);
C#
// Create the proposal line item on the server.
ProposalLineItem[] proposalLineItems = proposalLineItemService.createProposalLineItems(
new ProposalLineItem[] { proposalLineItem });
后续步骤
- 提交提案以供审批
- 审批 WorkflowConditionRequests