このガイドでは、商品の概要と、API で ProductTemplate オブジェクトを使って Product オブジェクトを作成する方法について説明します。
はじめに
DFP セールス マネージャの商品とは、販売する在庫のセグメントを表すもので、営業チームが作成します。エンティティとして見ると、商品は広告申込情報のプロポーザル、つまり ProposalLineItem オブジェクトを作成するためのテンプレートです。商品テンプレートを作成すると、商品はバックグラウンドで自動的に作成されます。
商品では、プロポーザル広告申込情報の各フィールドの既定値を定義します。名前、商品タイプ、レートタイプ、ターゲティング初期設定といったフィールドがあります。ターゲティング初期設定は、デフォルトで設定するターゲティングや、カスタマイズ可能にするターゲティング フィールドを指定するものです。プロポーザル広告申込情報は、RateCard オブジェクトと Product オブジェクト（有効にした後）を組み合わせて作成されます。
商品を作成する
商品を作成するには、まずローカルで ProductTemplate オブジェクトを作成します。次にオブジェクトの定義として、名前と、必要に応じてカタログ内の他の商品テンプレートと区別するための説明を指定します。
Java
// Create a product template.
ProductTemplate productTemplate = new ProductTemplate();
productTemplate.setName("Product template #" + new Random().nextInt(Integer.MAX_VALUE));
productTemplate.setDescription("This product template creates standard proposal line items "
+ "targeting Chrome browsers with product segmentation on ad units and geo targeting.");
Python
# Initialize appropriate service.
product_template_service = client.GetService(
'ProductTemplateService', version='v201708')
# Create a product template.
product_template = {
'name': ('Product template #%d' % uuid.uuid4()),
'description': ('This product template creates standard proposal line '
'items targeting Chrome browsers with product '
'segmentation on ad units and geo targeting.'),
...
PHP
$productTemplateService = $dfpServices->get($session, ProductTemplateService::class);
$productTemplate = new ProductTemplate();
$productTemplate->setName('Product template #' . uniqid());
$productTemplate->setDescription(
'This product template creates standard '
. 'proposal line items targeting Chrome browsers with product '
. 'segmentation on ad units and geo targeting.'
);
C#
using (ProductTemplateService productTemplateService =
(ProductTemplateService) user.GetService(DfpService.v201708.ProductTemplateService))
// Create a product template.
ProductTemplate productTemplate = new ProductTemplate();
productTemplate.name = "Product template #" + new Random().Next(int.MaxValue);
productTemplate.description = "This product template creates standard proposal line items "
+ "targeting Chrome browsers with product segmentation on ad units and geo targeting.";
ここで名前マクロを設定できます。このフィールドにより、作成される商品の名前が生成されます。指定した商品セグメントに基づいて、1 つの商品テンプレートから複数の商品が作成されます。
Java
// Set the name macro which will be used to generate the names of the products.
// This will create a segmentation based on the line item type, ad unit, and location.
productTemplate.setNameMacro("<line-item-type> - <ad-unit> - <template-name> - <location>");
Python
...
'nameMacro': ('<line-item-type> - <ad-unit> - '
'<template-name> - <location>'),
...
PHP
// Set the name macro which will be used to generate the names of the
// products. This will create a segmentation based on the line item type, ad
// unit, and location.
$productTemplate->setNameMacro(
'<line-item-type> - <ad-unit> - <template-name> - <location>'
);
C#
// Set the name macro which will be used to generate the names of the products.
// This will create a segmentation based on the line item type, ad unit, and location.
productTemplate.nameMacro = "<line-item-type> - <ad-unit> - <template-name> - <location>";
以下のフィールドは、プロポーザル広告申込情報の入稿仕様（広告申込情報タイプ、商品タイプ、料金、クリエイティブ、クリエイティブの配信設定など）に関連したものです。
Java
// Set the product type so the created proposal line items will be trafficked in DFP.
productTemplate.setProductType(ProductType.DFP);
// Set rate type to create CPM priced proposal line items.
productTemplate.setRateType(RateType.CPM);
productTemplate.setDeliveryRateType(DeliveryRateType.AS_FAST_AS_POSSIBLE);
// Optionally set the creative rotation of the product to serve one or more creatives.
productTemplate.setRoadblockingType(RoadblockingType.ONE_OR_MORE);
// Create the master creative placeholder.
CreativePlaceholder creativeMasterPlaceholder = new CreativePlaceholder();
creativeMasterPlaceholder.setSize(new Size(728, 90, false));
// Create companion creative placeholders.
CreativePlaceholder companionCreativePlaceholder = new CreativePlaceholder();
companionCreativePlaceholder.setSize(new Size(300, 250, false));
// Set the size of creatives that can be associated with the product template.
productTemplate.setCreativePlaceholders(
new CreativePlaceholder[] {creativeMasterPlaceholder, companionCreativePlaceholder});
// Set the type of proposal line item to be created from the product template.
productTemplate.setLineItemType(LineItemType.STANDARD);
Python
...
'productType': 'DFP',
'rateType': 'CPM',
'roadblockingType': 'ONE_OR_MORE',
'deliveryRateType': 'AS_FAST_AS_POSSIBLE',
'creativePlaceholders': [
{
'size': {
'width': '728',
'height': '90'
}
},
{
'size': {
'width': '300',
'height': '250'
}
}
],
'lineItemType': 'STANDARD',
...
PHP
// Set the product type so the created proposal line items will be
// trafficked in DFP.
$productTemplate->setProductType(ProductType::DFP);
// Set rate type to create CPM priced proposal line items.
$productTemplate->setRateType(RateType::CPM);
$productTemplate->setDeliveryRateType(
DeliveryRateType::AS_FAST_AS_POSSIBLE
);
// Optionally set the creative rotation of the product to serve one or more
// creatives.
$productTemplate->setRoadblockingType(RoadblockingType::ONE_OR_MORE);
// Set the size of creatives that can be associated with the product
// template.
$creativePlaceholder1 = new CreativePlaceholder();
$size = new Size();
$size->setWidth(728);
$size->setHeight(90);
$size->setIsAspectRatio(false);
$creativePlaceholder1->setSize($size);
$creativePlaceholder2 = new CreativePlaceholder();
$size = new Size();
$size->setWidth(300);
$size->setHeight(250);
$size->setIsAspectRatio(false);
$creativePlaceholder2->setSize($size);
$productTemplate->setCreativePlaceholders(
[$creativePlaceholder1, $creativePlaceholder2]
);
// Set the type of proposal line item to be created from the product
// template.
$productTemplate->setLineItemType(LineItemType::STANDARD);
C#
// Set the product type so the created proposal line items will be trafficked in DFP.
productTemplate.productType = ProductType.DFP;
// Set rate type to create CPM priced proposal line items.
productTemplate.rateType = RateType.CPM;
// Optionally set the creative rotation of the product to serve one or more creatives.
productTemplate.roadblockingType = RoadblockingType.ONE_OR_MORE;
productTemplate.deliveryRateType = DeliveryRateType.AS_FAST_AS_POSSIBLE;
// Create the master creative placeholder.
CreativePlaceholder creativeMasterPlaceholder = new CreativePlaceholder();
creativeMasterPlaceholder.size =
new Size() { width = 728, height = 90, isAspectRatio = false };
// Create companion creative placeholders.
CreativePlaceholder companionCreativePlaceholder = new CreativePlaceholder();
companionCreativePlaceholder.size =
new Size() { width = 300, height = 250, isAspectRatio = false };
// Set the size of creatives that can be associated with the product template.
productTemplate.creativePlaceholders =
new CreativePlaceholder[] { creativeMasterPlaceholder, companionCreativePlaceholder };
// Set the type of proposal line item to be created from the product template.
productTemplate.lineItemType = LineItemType.STANDARD;
次に、商品にターゲティングの既定値を定義します。この値は商品から作成されるプロポーザル広告申込情報に継承されます。 同様に、プロポーザル広告申込情報のターゲティングは商品テンプレートに直接追加できます。 これは ProductTemplateTargeting オブジェクトを使用して行います。
Java
// Get the root ad unit ID used to target the whole site.
String rootAdUnitId = networkService.getCurrentNetwork().getEffectiveRootAdUnitId();
// Create ad unit targeting for the root ad unit (i.e. the whole network).
AdUnitTargeting adUnitTargeting = new AdUnitTargeting();
adUnitTargeting.setAdUnitId(rootAdUnitId);
adUnitTargeting.setIncludeDescendants(true);
// Create geo targeting for the US.
Location countryLocation = new Location();
countryLocation.setId(2840L);
// Create geo targeting for Hong Kong.
Location regionLocation = new Location();
regionLocation.setId(2344L);
GeoTargeting geoTargeting = new GeoTargeting();
geoTargeting.setTargetedLocations(new Location[] {countryLocation, regionLocation});
// Add browser targeting to Chrome on the product template distinct from product segmentation.
Browser chromeBrowser = new Browser();
chromeBrowser.setId(500072L);
BrowserTargeting browserTargeting = new BrowserTargeting();
browserTargeting.setBrowsers(new Browser[] {chromeBrowser});
TechnologyTargeting technologyTargeting = new TechnologyTargeting();
technologyTargeting.setBrowserTargeting(browserTargeting);
Targeting productTemplateTargeting = new Targeting();
productTemplateTargeting.setTechnologyTargeting(technologyTargeting);
productTemplate.setBuiltInTargeting(productTemplateTargeting);
Python
...
'customizableAttributes': {
'allowPlacementTargetingCustomization': True,
},
'builtInTargeting': {
'technologyTargeting': {
# Set browser targeting to Chrome.
'browserTargeting': {
{
'browsers': [
{
'id': '500072'
}
]
}
}
}
},
...
PHP
// Add browser targeting to Chrome on the product template distinct from
// product segmentation.
$targeting = new Targeting();
$technologyTargeting = new TechnologyTargeting();
$browserTargeting = new BrowserTargeting();
$browser = new Browser();
$browser->setId(500072);
$browserTargeting->setBrowsers([$browser]);
$technologyTargeting->setBrowserTargeting($browserTargeting);
$targeting->setTechnologyTargeting($technologyTargeting);
$productTemplate->setBuiltInTargeting($targeting);
// Allow placement targeting to be customized on the proposal line item.
$customizableAttributes = new CustomizableAttributes();
$customizableAttributes->setAllowPlacementTargetingCustomization(true);
$productTemplate->setCustomizableAttributes($customizableAttributes);
// Add inventory and geo targeting as product segmentation.
$productSegmentation = new ProductSegmentation();
// Create ad unit targeting for the root ad unit (i.e. the whole network).
$adUnitTargeting = new AdUnitTargeting();
$adUnitTargeting->setAdUnitId(
$networkService->getCurrentNetwork()
->getEffectiveRootAdUnitId()
);
$adUnitTargeting->setIncludeDescendants(true);
$productSegmentation->setAdUnitSegments([$adUnitTargeting]);
// Create geo targeting for the US and Hong Kong.
$geoTargeting = new GeoTargeting();
$location1 = new Location();
$location1->setId(2840); // US
$location2 = new Location();
$location2->setId(2344); // Hong Kong
$geoTargeting->setTargetedLocations([$location1, $location2]);
C#
// Get the root ad unit ID used to target the whole site.
String rootAdUnitId = networkService.getCurrentNetwork().effectiveRootAdUnitId;
// Create ad unit targeting for the root ad unit (i.e. the whole network).
AdUnitTargeting adUnitTargeting = new AdUnitTargeting();
adUnitTargeting.adUnitId = rootAdUnitId;
adUnitTargeting.includeDescendants = true;
// Create geo targeting for the US.
Location countryLocation = new Location();
countryLocation.id = 2840L;
// Create geo targeting for Hong Kong.
Location regionLocation = new Location();
regionLocation.id = 2344L;
GeoTargeting geoTargeting = new GeoTargeting();
geoTargeting.targetedLocations = new Location[] { countryLocation, regionLocation };
// Add browser targeting to Chrome on the product template distinct from product
// segmentation.
Browser chromeBrowser = new Browser();
chromeBrowser.id = 500072L;
BrowserTargeting browserTargeting = new BrowserTargeting();
browserTargeting.browsers = new Browser[] { chromeBrowser };
TechnologyTargeting technologyTargeting = new TechnologyTargeting();
technologyTargeting.browserTargeting = browserTargeting;
Targeting productTemplateTargeting = new Targeting();
productTemplateTargeting.technologyTargeting = technologyTargeting;
productTemplate.builtInTargeting = productTemplateTargeting;
productTemplate.customizableAttributes = new CustomizableAttributes() {
allowPlacementTargetingCustomization = true
};
商品セグメントを使用すると、複数のターゲティング オプションの組み合わせを基に、一連のプロポーザル広告申込情報の設定を共有する複数の商品を作成できます。 上記のセクションでは、GeoTargeting オブジェクトに対して複数の場所を追加しました。 これを 1 つのセグメントとして商品テンプレートに追加すると、米国と香港をそれぞれターゲットとする 2 つの商品が作成されます。
Java
// Add inventory and geo targeting as product segmentation.
ProductSegmentation productSegmentation = new ProductSegmentation();
productSegmentation.setAdUnitSegments(new AdUnitTargeting[] {adUnitTargeting});
productSegmentation.setGeoSegment(geoTargeting);
productTemplate.setProductSegmentation(productSegmentation);
Python
...
'productSegmentation': {
'geoSegment': {
'targetedLocations': [
{'id': '2840',
'displayName': 'US'},
{'id': '2344',
'displayName': 'Hong Kong'}
]
},
'adUnitSegments': [{
'adUnitId': (network_service.getCurrentNetwork()[
'effectiveRootAdUnitId']),
'includeDescendants': 'true'
}]
}
...
PHP
$productSegmentation->setGeoSegment($geoTargeting);
$productTemplate->setProductSegmentation($productSegmentation);
C#
// Add inventory and geo targeting as product segmentation.
ProductSegmentation productSegmentation = new ProductSegmentation();
productSegmentation.adUnitSegments = new AdUnitTargeting[] { adUnitTargeting };
productSegmentation.geoSegment = geoTargeting;
productTemplate.productSegmentation = productSegmentation;
これらのフィールドを設定し、商品テンプレートの配列に対して createProductTemplates を呼び出すと、新しい ProductTemplate オブジェクトが作成されます。
Java
// Create the product template on the server.
ProductTemplate[] productTemplates =
productTemplateService.createProductTemplates(new ProductTemplate[] {productTemplate});
Python
# Create product templates on the server.
product_templates = product_template_service.createProductTemplates(
[product_template])
PHP
// Create the product template on the server.
$results = $productTemplateService->createProductTemplates([$productTemplate]);
C#
// Create the product template on the server.
ProductTemplate[] productTemplates = productTemplateService.createProductTemplates(
new ProductTemplate[] { productTemplate });
商品テンプレートは INACTIVE ステータスで作成されます。対応する商品も同様です。
商品テンプレートを有効にする
商品テンプレートから作成される商品を使用できるようにするには、商品テンプレートを有効にする必要があります。 これには、ActivateProductTemplates アクションを使用します。
Java
// Create a statement to select a product template.
StatementBuilder statementBuilder = new StatementBuilder()
.where("WHERE id = :id")
.orderBy("id ASC")
.limit(StatementBuilder.SUGGESTED_PAGE_LIMIT)
.withBindVariableValue("id", productTemplateId);
// Create action.
com.google.api.ads.dfp.axis.v201708.ActivateProductTemplates action =
new com.google.api.ads.dfp.axis.v201708.ActivateProductTemplates();
// Perform action.
UpdateResult result =
productTemplateService.performProductTemplateAction(
action, statementBuilder.toStatement());
Python
# Create query.
statement = (dfp.StatementBuilder()
.Where('id = :id')
.WithBindVariable('id', long(product_template_id))
.Limit(1))
# Perform action.
result = product_template_service.performProductTemplateAction(
{'xsi_type': 'ActivateProductTemplates'}, statement.ToStatement())
PHP
// Create a statement to select the product templates to activate.
$pageSize = StatementBuilder::SUGGESTED_PAGE_LIMIT;
$statementBuilder = (new StatementBuilder())->where('id = :id')
->orderBy('id ASC')
->limit($pageSize)
->withBindVariableValue('id', $productTemplateId);
// Create and perform action.
$action = new ActivateProductTemplatesAction();
$result = $productTemplateService->performProductTemplateAction(
$action,
$statementBuilder->toStatement()
);
C#
// Create statement to select a product template by ID.
StatementBuilder statementBuilder = new StatementBuilder()
.Where("id = :id")
.OrderBy("id ASC")
.Limit(StatementBuilder.SUGGESTED_PAGE_LIMIT)
.AddValue("id", productTemplateId);
// Create action.
Google.Api.Ads.Dfp.v201708.ActivateProductTemplates action =
new Google.Api.Ads.Dfp.v201708.ActivateProductTemplates();
// Perform action.
UpdateResult result = productTemplateService.performProductTemplateAction(action,
statementBuilder.ToStatement());
これで商品テンプレートと商品が有効になり、プロポーザル広告申込情報の作成に使用できるようになります。
商品を取得する
新しい ProductTemplate オブジェクトを作成した後、商品テンプレートによって返された ID を検索することで、作成済みの商品を再度取得できます。
Java
// Create a statement to select products.
StatementBuilder statementBuilder = new StatementBuilder()
.where("productTemplateId = :productTemplateId")
.orderBy("id ASC")
.limit(StatementBuilder.SUGGESTED_PAGE_LIMIT)
.withBindVariableValue("productTemplateId", productTemplateId);
ProductPage page =
productService.getProductsByStatement(statementBuilder.toStatement());
Python
# Create a statement to select products.
statement = (dfp.StatementBuilder()
.Where('productTemplateId = :productTemplateId')
.WithBindVariable('productTemplateId', product_template_id))
response = product_service.getProductsByStatement(statement.ToStatement())
PHP
// Create a statement to select products.
$pageSize = StatementBuilder::SUGGESTED_PAGE_LIMIT;
$statementBuilder =
(new StatementBuilder())->where('productTemplateId = :productTemplateId')
->orderBy(
'id ASC'
)
->limit($pageSize)
->withBindVariableValue('productTemplateId', $productTemplateId);
$page = $productService->getProductsByStatement(
$statementBuilder->toStatement()
);
C#
// Create a statement to select products.
int pageSize = StatementBuilder.SUGGESTED_PAGE_LIMIT;
StatementBuilder statementBuilder = new StatementBuilder()
.Where("productTemplateId = :productTemplateId")
.OrderBy("id ASC")
.Limit(pageSize)
.AddValue("productTemplateId", productTemplateId);
ProductPage page = productService.getProductsByStatement(
statementBuilder.ToStatement());
ローカルで商品を同期する
すべての商品のローカル カタログを作成する場合は、初回のクエリで次のようなステートメントを使ってすべての商品を選択します。
Java
StatementBuilder statementBuilder = new StatementBuilder()
.orderBy("id ASC")
.limit(StatementBuilder.SUGGESTED_PAGE_LIMIT);
Python
statement = dfp.FilterStatement('ORDER BY id ASC')
PHP
$statementBuilder->OrderBy('id ASC')
->Limit(StatementBuilder::SUGGESTED_PAGE_LIMIT);
C#
StatementBuilder statementBuilder = new StatementBuilder()
.OrderBy("id ASC")
.Limit(StatementBuilder.SUGGESTED_PAGE_LIMIT);
2 回目以降は、Product オブジェクトで lastModifiedDateTime プロパティを使用してフィルタリングします。
前回の同期の日付を lastModifiedDateTime 変数に渡すと、変更された商品のみを取得できるため、時間の短縮になります。
Java
StatementBuilder statementBuilder = new StatementBuilder()
.where("lastModifiedDateTime > :lastModifiedDateTime")
.orderBy("id ASC")
.limit(StatementBuilder.SUGGESTED_PAGE_LIMIT)
.withBindVariable("lastModifiedDateTime", lastSyncDateTime);
Python
values = [{
'key': 'dateTimeString',
'value': {
'xsi_type': 'TextValue',
'value': lastSyncDateTime.strftime('%Y-%m-%dT%H:%M:%S')
}
}, {
'key': 'orderId',
'value': {
'xsi_type': 'NumberValue',
'value': order_id
}
}]
query = 'WHERE lastModifiedDateTime >= :dateTimeString AND orderId = :orderId'
statement = dfp.FilterStatement(query, values)
PHP
$statementBuilder->Where('lastModifiedDateTime >= :lastModifiedDateTime')
->OrderBy('id ASC')
->Limit(StatementBuilder::SUGGESTED_PAGE_LIMIT)
->WithBindVariableValue(
'lastModifiedDateTime',
DateTimeUtils::ToDfpDateTime(lastSyncDateTime)
);
C#
StatementBuilder statementBuilder = new StatementBuilder()
.Where("lastModifiedDateTime > :lastModifiedDateTime")
.OrderBy("id ASC")
.Limit(StatementBuilder.SUGGESTED_PAGE_LIMIT)
.AddValue("lastModifiedDateTime", lastSyncDateTime);
ローカル版の「カタログ」にネットワークの商品をすべて追加しておくと、追加の API 呼び出しを行わなくてもそれらの商品を再利用できます。