はじめに
このガイドでは ForecastService について説明し、2 種類の予測機能（在庫予測と配信予測）の使い方を紹介します。
ForecastService の利用を開始するにあたっては、DFP の予測についてしっかりと理解しておくことが重要です。
在庫予測
在庫予測では、広告申込情報で予約可能な在庫の最大数を確認することができます。これは、管理画面の在庫の確認に似た機能です。
予測の結果には、使用可能数、一致数、獲得可能数、配信数、予約数が含まれます。また、AvailabilityForecastOptions で設定したオプションに応じて、すべての競合する広告申込情報や、ターゲティングの内訳ごとの使用可能数を含めることもできます。デフォルトではどちらも含まれません。
ターゲティングの内訳には、各ターゲティング条件に対する一致数と使用可能数が含まれます。この内訳項目は、広告申込情報のターゲティングに合わせて自動的に生成されます。たとえば、広告申込情報のターゲットを広告ユニット ID 123456 に設定した場合は、次のような内訳項目が含まれます。
<targetingCriteriaBreakdowns> <targetingDimension>AD_UNIT</targetingDimension> <targetingCriteriaId>123456</targetingCriteriaId> <targetingCriteriaName>My Ad Unit Name</targetingCriteriaName> <excluded>false</excluded> <availableUnits>1000</availableUnits> <matchedUnits>2300</matchedUnits> </targetingCriteriaBreakdowns>
在庫予測は、既存の広告申込情報、または調査広告申込情報に対して実行できます。
既存の広告申込情報
既存の広告申込情報に対して在庫予測を実行する場合は、既存の広告申込情報の ID を使用します。
Java
// Get the ForecastService.
ForecastServiceInterface forecastService =
dfpServices.get(session, ForecastServiceInterface.class);
// Get forecast for line item.
AvailabilityForecastOptions options = new AvailabilityForecastOptions();
options.setIncludeContendingLineItems(true);
options.setIncludeTargetingCriteriaBreakdown(true);
AvailabilityForecast forecast =
forecastService.getAvailabilityForecastById(lineItemId, options);
long matched = forecast.getMatchedUnits();
double availablePercent = (forecast.getAvailableUnits() / (matched * 1.0)) * 100;
String unitType = forecast.getUnitType().toString().toLowerCase();
System.out.printf("%d %s matched.%n", matched, unitType);
System.out.printf("%.2f%% %s available.%n", availablePercent, unitType);
if (forecast.getPossibleUnits() != null) {
double possiblePercent = (forecast.getPossibleUnits() / (matched * 1.0)) * 100;
System.out.printf("%.2f%% %s possible.%n", possiblePercent, unitType);
}
System.out.printf("%d contending line items.%n",
forecast.getContendingLineItems() == null ? 0 : forecast.getContendingLineItems().length);
Python
# Initialize appropriate service.
forecast_service = client.GetService('ForecastService', version='v201805')
# Set forecasting options.
forecast_options = {
'includeContendingLineItems': True,
'includeTargetingCriteriaBreakdown': True,
}
# Get forecast for line item.
forecast = forecast_service.getAvailabilityForecastById(
line_item_id, forecast_options)
matched = long(forecast['matchedUnits'])
available_units = long(forecast['availableUnits'])
if matched > 0:
available_percent = (float(available_units) / matched) * 100.
else:
available_percent = 0
contending_line_items = getattr(forecast, 'contentingLineItems', [])
# Display results.
print '%s %s matched.' % (matched, forecast['unitType'].lower())
print '%s%% %s available.' % (available_percent, forecast['unitType'].lower())
print '%d contending line items.' % len(contending_line_items)
if 'possibleUnits' in forecast and matched:
possible_percent = (long(forecast['possibleUnits'])/float(matched)) * 100.
print '%s%% %s possible' % (possible_percent, forecast['unitType'].lower())
PHP
$forecastService = $serviceFactory->createForecastService($session);
// Get forecast for line item.
$options = new AvailabilityForecastOptions();
$options->setIncludeContendingLineItems(true);
$options->setIncludeTargetingCriteriaBreakdown(true);
$forecast = $forecastService->getAvailabilityForecastById(
$lineItemId,
$options
);
// Print out forecast results.
$matchedUnits = $forecast->getMatchedUnits();
$unitType = strtolower($forecast->getUnitType());
printf("%d %s matched.\n", $matchedUnits, $unitType);
if ($matchedUnits > 0) {
$percentAvailableUnits = $forecast->getAvailableUnits() / $matchedUnits * 100;
$percentPossibleUnits = $forecast->getPossibleUnits() / $matchedUnits * 100;
printf("%.2d%% %s available.\n", $percentAvailableUnits, $unitType);
printf("%.2d%% %s possible.\n", $percentPossibleUnits, $unitType);
}
printf(
"%d contending line items.\n",
count($forecast->getContendingLineItems())
);
C#
using (ForecastService forecastService =
(ForecastService) user.GetService(DfpService.v201805.ForecastService)) {
// Get forecast for line item.
AvailabilityForecastOptions options = new AvailabilityForecastOptions();
options.includeContendingLineItems = true;
options.includeTargetingCriteriaBreakdown = true;
AvailabilityForecast forecast =
forecastService.getAvailabilityForecastById(lineItemId, options);
// Display results.
long matched = forecast.matchedUnits;
double availablePercent = (double) (forecast.availableUnits / (matched * 1.0)) * 100;
String unitType = forecast.unitType.ToString().ToLower();
Console.WriteLine("{0} {1} matched.\n{2} % {3} available.", matched, unitType,
availablePercent, unitType);
if (forecast.possibleUnitsSpecified) {
double possiblePercent = (double) (forecast.possibleUnits / (matched * 1.0)) * 100;
Console.WriteLine(possiblePercent + "% " + unitType + " possible.\n");
}
Console.WriteLine("{0} contending line items.", (forecast.contendingLineItems != null) ?
forecast.contendingLineItems.Length : 0);
Ruby
# Get the ForecastService.
forecast_service = dfp.service(:ForecastService, API_VERSION)
# Set forecasting options.
forecast_options = {
:include_contending_line_items => True,
:include_targeting_criteria_breakdown => True,
}
# Get forecast for the line item.
forecast = forecast_service.get_availability_forecast_by_id(
line_item_id, forecast_options
)
unless forecast.nil?
# Display results.
matched = forecast[:matched_units]
available_percent = forecast[:available_units] * 100.0 / matched
unit_type = forecast[:unit_type].to_s.downcase
puts '%.2f %s matched.' % [matched, unit_type]
puts '%.2f%% of %s available.' % [available_percent, unit_type]
puts '%d contending line items.' % forecast[:contending_line_items].size
unless forecast[:possible_units].nil?
possible_percent = forecast[:possible_units] * 100.0 / matched
puts '%.2f%% of %s possible.' % [possible_percent, unit_type]
end
end
この例では、次のような結果が返されます。
100 clicks matched. 2 contending line items.
調査広告申込情報
調査広告申込情報を作成し、それを一時的に使用して予測を実行することもできます。この場合はローカルの広告申込情報を作成し、ProspectiveLineItem でその広告申込情報を設定します。広告主 ID を設定すると、予測では統合タイプのブロックルールも考慮されます。
Java
// Get forecast for prospective line item.
ProspectiveLineItem prospectiveLineItem = new ProspectiveLineItem();
prospectiveLineItem.setAdvertiserId(advertiserId);
prospectiveLineItem.setLineItem(lineItem);
AvailabilityForecastOptions options = new AvailabilityForecastOptions();
options.setIncludeContendingLineItems(true);
options.setIncludeTargetingCriteriaBreakdown(true);
AvailabilityForecast forecast =
forecastService.getAvailabilityForecast(prospectiveLineItem, options);
Python
prospective_line_item = {
'lineItem': line_item,
'advertiserId': advertiser_id
}
# Set forecasting options.
forecast_options = {
'includeContendingLineItems': True,
'includeTargetingCriteriaBreakdown': True,
}
# Get forecast.
forecast = forecast_service.getAvailabilityForecast(
prospective_line_item, forecast_options)
PHP
// Get forecast for prospective line item.
$prospectiveLineItem = new ProspectiveLineItem();
$prospectiveLineItem->setAdvertiserId($advertiserId);
$prospectiveLineItem->setLineItem($lineItem);
$options = new AvailabilityForecastOptions();
$options->setIncludeContendingLineItems(true);
$options->setIncludeTargetingCriteriaBreakdown(true);
$forecast = $forecastService->getAvailabilityForecast(
$prospectiveLineItem,
$options
);
C#
// Get availability forecast.
AvailabilityForecastOptions options = new AvailabilityForecastOptions();
options.includeContendingLineItems = true;
options.includeTargetingCriteriaBreakdown = true;
ProspectiveLineItem prospectiveLineItem = new ProspectiveLineItem();
prospectiveLineItem.advertiserId = advertiserId;
prospectiveLineItem.lineItem = lineItem;
AvailabilityForecast forecast =
forecastService.getAvailabilityForecast(prospectiveLineItem, options);
Ruby
prospective_line_item = {
:advertiser_id => advertiser_id,
:line_item => line_item
}
# Set forecasting options.
forecast_options = {
:include_contending_line_items => true,
:include_targeting_criteria_breakdown => true,
}
# Get forecast for the line item.
forecast = forecast_service.get_availability_forecast(
prospective_line_item, forecast_options)
配信予測
複数の競合する広告申込情報の配信についてシミュレーションを行う場合は、DeliveryForecast を使用します。これは、管理画面の販売管理の予測に似た機能です。
既存の広告申込情報
既存の広告申込情報に対して配信予測を実行する場合は、既存の広告申込情報の ID を使用します。
Java
// Get the ForecastService.
ForecastServiceInterface forecastService =
dfpServices.get(session, ForecastServiceInterface.class);
DeliveryForecastOptions options = new DeliveryForecastOptions();
DeliveryForecast forecast = forecastService.getDeliveryForecastByIds(
Longs.toArray(lineItemIds), options);
for (LineItemDeliveryForecast lineItemForecast : forecast.getLineItemDeliveryForecasts()) {
String unitType = lineItemForecast.getUnitType().toString().toLowerCase();
System.out.printf("Forecast for line item %d:%n", lineItemForecast.getLineItemId());
System.out.printf("\t%d %s matched%n", lineItemForecast.getMatchedUnits(), unitType);
System.out.printf("\t%d %s delivered%n", lineItemForecast.getDeliveredUnits(), unitType);
System.out.printf("\t%d %s predicted%n",
lineItemForecast.getPredictedDeliveryUnits(), unitType);
}
Python
# Initialize appropriate service.
forecast_service = client.GetService('ForecastService', version='v201805')
# Get forecast for line item.
forecast = forecast_service.getDeliveryForecastByIds(
[line_item_id1, line_item_id2], None)
for single_forecast in forecast['lineItemDeliveryForecasts']:
unit_type = single_forecast['unitType']
print ('Forecast for line item %d:\n\t%d %s matched\n\t%d %s delivered\n\t'
'%d %s predicted\n' % (
single_forecast['lineItemId'], single_forecast['matchedUnits'],
unit_type, single_forecast['deliveredUnits'], unit_type,
single_forecast['predictedDeliveryUnits'], unit_type))
if __name__ == '__main__':
# Initialize client object.
dfp_client = dfp.DfpClient.LoadFromStorage()
main(dfp_client, LINE_ITEM_ID_1, LINE_ITEM_ID_2)
PHP
$forecastService = $serviceFactory->createForecastService($session);
// Get forecast for the line items with no options set.
$forecast = $forecastService->getDeliveryForecastByIds(
[$lineItemId1, $lineItemId2],
new DeliveryForecastOptions()
);
// Print out forecast results.
foreach ($forecast->getLineItemDeliveryForecasts() as $lineItemForecast) {
$unitType = strtolower($lineItemForecast->getUnitType());
printf(
"Forecast for line item ID %d:\n",
$lineItemForecast->getLineItemId()
);
printf(
" %d %s matched\n",
$lineItemForecast->getMatchedUnits(),
$unitType
);
printf(
" %d %s delivered\n",
$lineItemForecast->getDeliveredUnits(),
$unitType
);
printf(
" %d %s predicted\n",
$lineItemForecast->getPredictedDeliveryUnits(),
$unitType
);
}
C#
using (ForecastService forecastService =
(ForecastService) user.GetService(DfpService.v201805.ForecastService)) {
// Get a delivery forecast for the line items.
DeliveryForecastOptions options = new DeliveryForecastOptions();
options.ignoredLineItemIds = new long[] { };
DeliveryForecast forecast = forecastService.getDeliveryForecastByIds(
new long[] { lineItemId1, lineItemId2 }, options);
// Display results.
foreach (LineItemDeliveryForecast lineItemForecast in
forecast.lineItemDeliveryForecasts) {
String unitType = lineItemForecast.unitType.GetType().Name.ToLower();
Console.WriteLine("Forecast for line item {0}:", lineItemForecast.lineItemId);
Console.WriteLine("\t{0} {1} matched", lineItemForecast.matchedUnits, unitType);
Console.WriteLine("\t{0} {1} delivered", lineItemForecast.deliveredUnits, unitType);
Console.WriteLine("\t{0} {1} predicted", lineItemForecast.predictedDeliveryUnits,
unitType);
}
Ruby
# Get the ForecastService.
forecast_service = dfp.service(:ForecastService, API_VERSION)
# Get forecast for the line item.
forecast = forecast_service.get_delivery_forecast_by_ids(
[line_item_id1, line_item_id2], nil)
unless forecast.nil? || forecast[:line_item_delivery_forecasts].nil?
forecast[:line_item_delivery_forecasts].each do |single_forecast|
# Display results.
unit_type = single_forecast[:unit_type]
puts ('Forecast for line item %d:\n\t%d %s matched\n\t%d %s ' +
'delivered\n\t%d %s predicted\n') % [single_forecast[:line_item_id],
single_forecast[:matched_units], unit_type,
single_forecast[:delivered_units], unit_type,
single_forecast[:predicted_delivery_units], unit_type]
end
end
この例では、次のような結果が返されます。
Forecast for line item 14678:
100 clicks matched
0 clicks delivered
98 clicks predicted
配信のシミュレーションで除外したい広告申込情報がある場合は、DeliveryForecastOptions でその広告申込情報の ID を指定します。
調査広告申込情報
在庫予測と同様に、一時的な広告申込情報でも配信予測を実行できます。この場合は、ForecastService.getDeliveryForecast メソッドで ProspectiveLineItem オブジェクトを使用します。
よくある質問
在庫予測を実行したい広告申込情報が多くあります。1 回のリクエストで複数の予測を実行できますか？
いいえ。既存の広告申込情報または調査広告申込情報ごとに、在庫予測リクエストを作成する必要があります。
何度も予測を実行しているうちに、EXCEEDED_QUOTA エラーが表示されるようになりました。どうしたらよいですか？
予測は処理負荷が大きいので、サービスの信頼性を確保するために割り当て量が設けられています。少し時間をおいて、割り当てエラーとなった予測を再度実行してみてください。
NO_FORECAST_YET エラーや NOT_ENOUGH_INVENTORY エラーが発生する理由を教えてください。
予測はネットワークのトラフィック履歴に基づいて実行されますが、予測を実行するのに十分な履歴データが蓄積されていない場合があります。これらのエラーについて詳しくは、ForecastError のドキュメントをご覧ください。
AlternativeUnitTypeForecast とは何ですか？
これを使うと、他にどのような広告枠があるかがわかります。たとえば、CPC 広告申込情報について予測を実行した場合、代替ユニットタイプの予測結果にはインプレッション数に関する情報が表示されます。
DFP の予測全般について知りたいのですが。
予測に関するよくある質問に該当する内容があるかご確認ください。または、デベロッパー フォーラムで質問を投稿してください。