エンティティ読み取りファイルからの移行

エンティティ読み込みファイル（ERF）は、Google Cloud Storage で利用可能なパートナーのキャンペーン オブジェクトの JSON 表現です。

ERF は 2021 年 6 月に非推奨となり、2024 年 10 月 31 日に廃止されます。ERF は生成されなくなりました。Display & Video 360 API を使用して、ディスプレイ＆ビデオ 360 のリソースを取得します。

このガイドでは、エンティティ読み取りファイルから Display & Video 360 API に移行する方法について説明します。

  • 2 つのインターフェースの違いの概要
  • ERF テーブルと API サービスの比較
  • API によるエンティティの取得に関するガイダンスを提供する
  • 既存のデータのギャップを認識する
  • すべての ERF フィールドと類似の API リソース フィールドのマッピングを表示する

概要

ERF から Display & Video 360 API に移行する場合は、次のような重要な違いを考慮する必要があります。

  • データの更新頻度。ERF は毎日一括で生成され、API はリソースの最新バージョンを取得します。
  • リソース構造。この API は、ERF とは異なる JSON 構造を使用して、同じリソースタイプを表します。パブリック ターゲティング設定などの一部のリソースでは、異なる ID 空間が使用される場合があります。
  • 取得方法。ディスプレイ＆ビデオ 360 API では、ERF から提供される未加工の JSON ファイルとは異なり、リソースを個別に、ページネーションされたリストで、または BigQuery データ転送でのみ取得できます。
  • スコープ: パートナー ID でスコープが設定される ERF とは異なり、ほとんどの API リソースは広告主 ID でスコープが設定されます。レスポンスに含まれるリソースは、そのスコープ内のリソースに限定されます。

API での ERF データの表現

エンティティ読み込みファイルは、「公開」テーブルと「非公開」テーブルに分割されます。公開テーブルには、ターゲティング値など、すべてのユーザーが利用できる情報が含まれています。非公開テーブルには、クリエイティブや広告申込情報のリソースなど、パートナー固有のデータが格納されます。

ディスプレイ＆ビデオ 360 API では、この二分法は使用されません。代わりに、さまざまなサービスからさまざまな JSON 構造を使用して、これらの情報をすべて取得できるようにしています。このセクションでは、公開 ERF テーブルと非公開 ERF テーブルで提供される情報と、ディスプレイ＆ビデオ 360 API リソースとサービスで提供される情報を比較します。

公開情報

ERF 公開テーブルは、取得した限定公開リソースのターゲティング設定を解釈し、UI からアップロードされた構造化データファイル（SDF）バージョンのサブセットを使用してターゲティングを割り当てる際に、ユーザーが使用できる参照資料です。これらの参考資料はすべてのユーザーに共通するもので、マッピングに使用される数値 ID と、表示名などの詳細な情報で構成されています。

Display & Video 360 API を使用する場合は、targetingTypes.targetingOptions サービスを使用してターゲティングの参照情報を取得できます。一般公開テーブルと同様に、このサービスは特定のターゲティング タイプのターゲティング オプションの ID と詳細を提供します。ターゲティング オプション ID の取得を示すコードサンプルについては、既存のターゲティングを設定するページをご覧ください。

公開テーブルと SDF

SDF v7 より前では、エンティティ読み込みファイルと構造化データファイルは同じ ID 空間をターゲット設定に使用します。SDF を使用してターゲティング設定を解釈または割り当てるために ERF 公開テーブルを使用している SDF ユーザーは、代わりにディスプレイ＆ビデオ 360 の管理画面からこのリファレンス マテリアルを CSV 形式でダウンロードできます。

v7 以降は、構造化データファイル列のサブセットで使用される ID 空間が更新され、SDF が ERF から分離され、ディスプレイ &ビデオ 360 API との整合性が高まっています。詳細については、v7 移行ガイドとリファレンス ドキュメントをご覧ください。

非公開リソース

ERF の非公開テーブルには、パートナーが所有する非公開リソースの現在の設定の毎日のスナップショットが示されます。単一のパートナーの下で作成できるリソースの量は膨大であるため、これらのファイルが肥大化してダウンロードや処理が難しくなることがあります。

API では、各非公開テーブルには、そのリソースタイプの取得と管理のエンドポイントを提供する対応するサービスがあります。リソースは、各サービスのそれぞれの list メソッドを使用して一括で取得できます。API では、各リソースの JSON 構造が ERF と異なり、異なるフィールド名と共有リソースが使用されます。

リソースの ERF 表現で利用可能な特定の情報（リソースの割り当てられたターゲティング設定やチャンネルのサイトなど）は、API では元のリソースの子として表され、追加の API リクエストで取得する必要があります。

API でのエンティティの取得

ディスプレイ＆ビデオ 360 のリソースは、直接の API リクエストまたは BigQuery への自動インポートで取得できます。

直接 API リクエスト

各リソースタイプは、異なる API サービスを介して取得できます。リソースは個別に取得することも、一括で取得することもできます。その場合は、適切なサービスの get メソッドまたは list メソッドを使用します。ディスプレイ &ビデオ 360 API の list メソッドの重要なプロパティは次のとおりです。

  • 必要なスコープ。パートナーでスコープが設定される ERF とは異なり、API のほとんどのリソースは広告主でスコープが設定されます。パートナーの下にあるリソースタイプ（広告申込情報など）をすべて取得するには、そのパートナーの子広告主ごとに個別のリスト リクエストが必要になる場合があります。ただし、広告主やパートナーが所有するチャンネルなど、パートナーの直接の子は例外です。
  • ページネーション。API リスト メソッドでは、ページ分割を使用してレスポンスが適切なサイズ内に収まるようにし、ほとんどの個々のリクエスト レスポンス（ページ）を 100 個のリソースに制限しています。関連リソースの数がページサイズより大きい場合は、リストの完全なレスポンスの次のページを取得するために、連続したリスト呼び出しが必要です。リスト レスポンスをページングするコード例については、利用可能なターゲティング オプションの取得に関するターゲティング ガイドのページ をご覧ください。
  • ターゲティングの取得に必要な追加リクエスト。リソースのターゲティング設定は API JSON オブジェクトに含まれず、代わりに、割り当てられたターゲティング オプションと呼ばれる子リソースに含まれます。これらの子リソースは、別のリクエストで取得する必要があります。たとえば、advertisers.lineItems.list リクエストで取得した広告申込情報ごとに、すべてのターゲティング情報を取得するために個別の advertisers.lineItems.bulkListAssignedTargetingOptions リクエストを実行する必要があります。

リソースの取得を最適化する

ディスプレイ＆ビデオ 360 API では、1 つのエンティティ読み取りファイルで利用できる情報量を取得するために、複数のリクエストが必要になる場合があります。リソースの取得方法を最適化すると、必要なデータをより効率的に取得できます。

  • API への同時リクエストを行う。Display & Video 360 API は、広告主様ごとのプロジェクトあたりのリクエストレートの上限を使用してインフラストラクチャを保護します。この割り当て構造では、複数の広告主にわたるマルチスレッド ソリューションを実装できるため、必要なすべてのリソースの取得にかかる合計時間を短縮できます。ページネーションでは、特定のスコープ内の特定のタイプのすべてのリソースを連続した呼び出しで取得する必要がありますが、別のスコープ内または別のタイプのリソースの取得は同時に行うことができます。
  • リスト呼び出しでパラメータによるフィルタと並べ替えを利用して、関連するリソースのみを取得します。たとえば、過去 1 日以内に更新された広告申込情報のみを取得する場合は、advertisers.lineItems.list メソッドの filter パラメータを使用して、updateTime が指定したタイムスタンプより大きい広告申込情報のみを返すことができます。これにより、必要なリクエストの数を大幅に減らすことができます。
  • 定期的に使用する ID をキャッシュに保存して、不要な API リクエストを回避します。ターゲティング オプション ID や Google オーディエンス ID などの一部の参照情報は比較的安定しており、安全に保存できるため、使用のたびに取得する必要がなくなります。ただし、キャッシュに保存された値は、頻繁な変更や非推奨化を考慮して、週に 1 回確認する必要があります。

Display &Video 360 API に効率的にアクセスする方法については、割り当ての最適化ガイドをご覧ください。

BigQuery にインポートする

ディスプレイ &ビデオ 360 API の BigQuery コネクタを使用すると、ディスプレイ &ビデオ 360 のリソース設定を毎日自動的に BigQuery に直接インポートできます。構成は、ディスプレイ＆ビデオ 360 API リソース設計を使用して BigQuery に保存されます。API リソースのサブセットがサポートされています。

Display &Video 360 API の BigQuery Connector の使用方法については、次のクラウドのドキュメントをご覧ください。

既知の API データのギャップ

ERF からディスプレイ＆ビデオ 360 API に移行する際には、次のようなデータのギャップが発生する可能性があります。

  • ストーリー広告掲載オーダー:ストーリーの広告掲載オーダーは API で取得できません。ディスプレイ＆ビデオ 360 の管理画面から取得する必要があります。
  • リソース フィールドのサブセット。ERF オブジェクトに存在する少数のリソース フィールドは、ディスプレイ &ビデオ 360 API で取得された対応するリソースでは使用できません。

付録: ERF フィールドと API のマッピング

公開テーブルのマッピング

以下の表は、ERF 公開テーブルのフィールドを、ディスプレイ＆ビデオ 360 API の既存のターゲティング タイプとターゲティング オプション フィールドにマッピングしたものです。1 つのフィールドの値が別のフィールドにマッピングされる場合でも、同じデータ型、列挙値、ID 空間を使用するとは限りません。

アプリ コレクション

ターゲティング タイプ TARGETING_TYPE_APP_CATEGORY で取得できます。

ERF フィールド名ディスプレイ＆ビデオ 360 API の提供状況
id TargetingOption.targetingOptionId フィールド。
name TargetingOption.appCategoryDetails.displayName フィールド。

ブラウザ

ターゲティング タイプ TARGETING_TYPE_BROWSER で取得できます。

ERF フィールド名ディスプレイ＆ビデオ 360 API の提供状況
id TargetingOption.targetingOptionId フィールド。
is_mobile 利用できません。
name TargetingOption.browserDetails.displayName フィールド。

DataPartner

ディスプレイ＆ビデオ 360 API には、同等のリソースやフィールドはありません。

DeviceCriteria

ターゲティング タイプ TARGETING_TYPE_OPERATING_SYSTEM、TARGETING_TYPE_DEVICE_MAKE_MODEL、TARGETING_TYPE_DEVICE_TYPE で取得できます。

ERF フィールド名ディスプレイ＆ビデオ 360 API の提供状況
id TargetingOption.targetingOptionId フィールドまたは DeviceType 列挙型。
is_mobile 利用できません。
name ターゲティング タイプに応じて、 TargetingOption.operatingSystemDetails.displayName フィールド、 TargetingOption.deviceMakeModelDetails.displayName フィールド、または DeviceType 列挙型。
criteria_type TargetingOption.targetingType フィールド。
operating_system_id 利用できません。
mobile_brand_name 利用できません。
mobile_model_name 利用できません。
mobile_make_model_id 利用できません。
device_type DeviceType 列挙型。

GeoLocation

ターゲティング タイプ TARGETING_TYPE_GEO_REGION で取得できます。

ERF フィールド名ディスプレイ＆ビデオ 360 API の提供状況
id TargetingOption.targetingOptionId フィールド。
canonical_name TargetingOption.geoRegionDetails.displayName フィールド。
geo_name 利用できません。
country_code 利用できません。
region_code 利用できません。
city_name 利用できません。
postal_name 利用できません。
dma_code 利用できません。

Isp

ターゲティング タイプ TARGETING_TYPE_CARRIER_AND_ISP で取得できます。

ERF フィールド名ディスプレイ＆ビデオ 360 API の提供状況
id TargetingOption.targetingOptionId フィールド。
is_mobile 利用できません。
name TargetingOption.carrierAndIspDetails.displayName フィールド。
secondary_criteria_id TargetingOption.targetingOptionId フィールド。

言語

ターゲティング タイプ TARGETING_TYPE_LANGUAGE で取得できます。

ERF フィールド名ディスプレイ＆ビデオ 360 API の提供状況
id TargetingOption.targetingOptionId フィールド。
name 利用できません。言語の完全な表示名は、 TargetingOption.languageDetails.displayName フィールドで確認できます。

SiteToPlacementId

ディスプレイ＆ビデオ 360 API には、同等のリソースやフィールドはありません。

SupportedExchange

ターゲティング タイプ TARGETING_TYPE_EXCHANGE で取得できます。

ERF フィールド名ディスプレイ＆ビデオ 360 API の提供状況
id Exchange 列挙型。
name Exchange 列挙型。

UniversalSite

ディスプレイ＆ビデオ 360 API には、同等のリソースやフィールドはありません。個々のサイトとアプリは、それぞれターゲティング タイプ TARGETING_TYPE_URL と TARGETING_TYPE_APP で直接ターゲットに設定できます。ディスプレイ＆ビデオ 360 では、任意のアプリや URL をターゲットに設定できますが、すべてのアプリや URL をレポートに含めることはできません。レポート対象外のアプリや URL を費用から除外する場合は、ディスプレイ&ビデオ 360 ヘルプセンターの手順に従ってください。

非公開テーブルのフィールド マッピング

次の表に、ERF 非公開テーブルのフィールドと、ディスプレイ＆ビデオ 360 API の既存のフィールドまたはサービスとの対応を示します。1 つのフィールドの値が別のフィールドにマッピングされている場合でも、同じデータ型、列挙型の値、ID 空間が使用されているとは限りません。

広告主

ERF フィールド名ディスプレイ＆ビデオ 360 API の提供状況
common_data.id Advertiser.advertiserId フィールド。
common_data.name Advertiser.displayName フィールド。
common_data.active Advertiser.entityStatus フィールド。
common_data.integration_code Advertiser.integrationDetails.integrationCode フィールド。
partner_id Advertiser.partnerId フィールド。
currency_code Advertiser.generalConfig.currencyCode フィールド。
timezone_code Advertiser.generalConfig.timeZone フィールド。
landing_page_url Advertiser.generalConfig.domainUrl フィールド。
available_channel_ids advertisers.channels.list メソッドで取得できます。
blacklist_channel_id ターゲティング タイプ TARGETING_TYPE_CHANNEL の advertisers.targetingTypes.assignedtargetingOptions.list メソッドで取得できます。 AssignedTargetingOption.channelDetails.negative が true の場合、チャンネルはネガティブ ターゲティングされています。
dcm_configuration 利用できません。
dcm_network_id Advertiser.adServerConfig.cmHybridConfig.cmAccountId フィールド。
dcm_advertiser_id Advertiser.adServerConfig.cmHybridConfig.cmAdvertiserIds フィールドには、キャンペーン マネージャー 360 の Floodlight 設定を共有するキャンペーン マネージャー 360 広告主 ID が一覧表示されます。
dcm_floodlight_group_id Advertiser.adServerConfig.cmHybridConfig.cmFloodlightConfigId フィールド。
dcm_syncable_site_ids Advertiser.adServerConfig.cmHybridConfig.cmSyncableSiteIds フィールド。
enable_oba_tags 利用できません。

キャンペーン

ERF フィールド名ディスプレイ＆ビデオ 360 API の提供状況
common_data.id Campaign.campaignId フィールド。
common_data.name Campaign.displayName フィールド。
common_data.active Campaign.entityStatus フィールド。
common_data.integration_code 利用できません。
advertiser_id Campaign.advertiserId フィールド。
予算 Campaign.campaignFlight フィールドと Campaign.campaignBudgets フィールド。
frequency_cap Campaign.frequencyCap フィールド。
default_target_list advertisers.campaigns.bulkListCampaignAssignedTargetingOptions メソッドで取得できます。
uses_video_creatives 利用できません。
uses_display_creatives 利用できません。
uses_audio_creatives 利用できません。
目標 Campaign.campaignGoal.campaignGoalType フィールド。
指標 Campaign.campaignGoal.performanceGoal.performanceGoalType フィールド。
objective_description Campaign.campaignGoal.performanceGoal.performanceGoalString フィールド。
metric_amount_micros Campaign.campaignGoal.performanceGoal.performanceGoalAmountMicros フィールド。

クリエイティブ

ERF フィールド名ディスプレイ＆ビデオ 360 API の提供状況
common_data.id Creative.creativeId フィールド。
common_data.name Creative.displayName フィールド。
common_data.active Creative.entityStatus フィールド。
common_data.integration_code Creative.integrationCode フィールド。
advertiser_id Creative.advertiserId フィールド。
dcm_placement_id Creative.cmPlacementId フィールド。
width_pixels Creative.dimensions.widthPixels フィールド。
height_pixels Creative.dimensions.heightPixels フィールド。
approval_status Creative.reviewStatus フィールド。
expanding_direction Creative.expandingDirection フィールド。
creative_type Creative.creativeType フィールド。

CustomAffinity

ERF フィールド名ディスプレイ＆ビデオ 360 API の提供状況
id CustomList.customListId フィールド。
name CustomList.displayName フィールド。
description 利用できません。
advertiser_id 利用できません。

FloodlightActivity

ERF フィールド名ディスプレイ＆ビデオ 360 API の提供状況
common_data.id FloodlightActivity.floodlightActivityId フィールド。
common_data.name FloodlightActivity.displayName フィールド。
common_data.active FloodlightActivity.servingStatus フィールド。
common_data.integration_code 利用できません。
advertiser_id FloodlightActivity.advertiserIds フィールドには、指定したパートナーの Floodlight アクティビティにアクセスできるすべての広告主が一覧表示されます。
partner_id floodlightGroups.floodlightActivities サービスへのリクエスト時にユーザーが指定します。
remarketing_enabled FloodlightActivity.remarketingConfigs フィールドには、指定したパートナーの Floodlight アクティビティにアクセスできる広告主ごとに、この設定が一覧表示されます。
ssl_required FloodlightActivity.sslRequired フィールド。

InsertionOrder

ERF フィールド名ディスプレイ＆ビデオ 360 API の提供状況
common_data.id InsertionOrder.insertionOrderId フィールド。
common_data.name InsertionOrder.displayName フィールド。
common_data.active InsertionOrder.entityStatus フィールド。
common_data.integration_code InsertionOrder.integrationDetails.integrationCode フィールド。
advertiser_id InsertionOrder.advertiserId フィールド。
campaign_id InsertionOrder.campaignId フィールド。
overall_budget 利用できません。 InsertionOrder.budget.budgetSegments フィールドの内容を使用して計算できます。
scheduled_segments InsertionOrder.budget.budgetSegments フィールド。
frequency_cap InsertionOrder.frequencyCap フィールド。
default_partner_costs InsertionOrder.partnerCosts フィールド。
default_target_list advertisers.insertionOrders.bulkListInsertionOrderAssignedTargetingOptions メソッドで取得できます。

InventorySource

ERF フィールド名ディスプレイ＆ビデオ 360 API の提供状況
id InventorySource.inventorySourceId フィールド。
未分類 利用できません。
inventory_name InventorySource.displayName フィールド。
exchange_id InventorySource.exchange フィールド。
accessing_advertisers InventorySource.readWriteAccessors フィールドと InventorySource.readAdvertiserIds フィールド。
external_id InventorySource.dealId フィールド。
min_cpm_micros InventorySource.rateDetails.rate.nanos フィールド。 InventorySource.rateDetails.inventorySourceRateType フィールドの値に応じて異なります。
min_cpm_currency_code InventorySource.rateDetails.rate.currencyCode フィールド。

LineItem

ERF フィールド名ディスプレイ＆ビデオ 360 API の提供状況
common_data.id LineItem.lineItemId フィールド。
common_data.name LineItem.displayName フィールド。
common_data.active LineItem.entityStatus フィールド。
common_data.integration_code LineItem.integrationDetails.integrationCode フィールド。
line_item_type LineItem.lineItemType フィールド。
insertion_order_id LineItem.insertionOrderId フィールド。
creative_ids LineItem.creativeIds フィールド。
max_cpm_advertiser_micros 使用している戦略スキームに応じて、 LineItem.bidStrategy.maximizeSpendAutoBid.maxAverageCpmBidAmountMicros フィールドまたは LineItem.bidStrategy.performanceGoalAutoBid.maxAverageCpmBidAmountMicros フィールド。
performance_goal LineItem.bidStrategy.maximizeSpendAutoBid.performanceGoalType または LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalType フィールド（使用する戦略スキームに応じて異なります）。
goal_advertiser_micros LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalAmountMicros フィールド。
partner_revenue_model LineItem.partnerRevenueModel フィールド。
cost_tracking_pixels LineItem.conversionCounting.floodlightActivityConfigs フィールド。
budget.start_time_usec LineItem.flight.dateRange.startDate フィールド。
budget.end_time_usec LineItem.flight.dateRange.endDate フィールド。
budget.max_impressions LineItem.budget.maxAmount フィールド（ LineItem.budget.budgetUnit が BUDGET_UNIT_IMPRESSIONS の場合）。
budget.max_spend_advertiser_micros LineItem.budget.maxAmount フィールド（ LineItem.budget.budgetUnit が BUDGET_UNIT_CURRENCY の場合）。
budget.pacing_type LineItem.pacing.pacingPeriod フィールド。
budget.pacing_max_impressions LineItem.pacing.dailyMaxImpressions フィールド。
budget.pacing_max_spend_advertiser_micros LineItem.pacing.dailyMaxMicros フィールド。
budget.pacing_distribution LineItem.pacing.pacingType フィールド。
frequency_cap LineItem.frequencyCap フィールド。
partner_costs LineItem.partnerCosts フィールド。
target_list advertisers.lineItems.bulkListLineItemAssignedTargetingOptions メソッドで取得できます。

NegativeKeywordList

ERF フィールド名ディスプレイ＆ビデオ 360 API の提供状況
id NegativeKeywordList.negativeKeywordListId フィールド。
name NegativeKeywordList.displayName フィールド。
advertiser_id NegativeKeywordList.advertiserId フィールド。

パートナー

ERF フィールド名ディスプレイ＆ビデオ 360 API の提供状況
common_data.id Partner.partnerId フィールド。
common_data.name Partner.displayName フィールド。
common_data.active Partner.entityStatus フィールド。
common_data.integration_code 利用できません。
currency_code Partner.generalConfig.currencyCode フィールド。
exchange_settings Partner.exchangeConfig.enabledExchanges フィールド。
default_partner_costs 利用できません。
default_partner_revenue 利用できません。
default_target_list 利用できません。

Google Pixel

Display &Video 360 API には同等のリソースやフィールドはありません。

UniversalChannel

ERF フィールド名ディスプレイ＆ビデオ 360 API の提供状況
id Channel.channelId フィールド。
name Channel.displayName フィールド。
site_ids owner のタイプに応じて、 advertisers.channels.sites.list メソッドと partners.channels.sites.list メソッドで取得できます。
accessing_advertisers 利用できません。
is_deleted 利用できません。
is_brand_safe_channel 利用できません。

UserList

ERF フィールド名ディスプレイ＆ビデオ 360 API の提供状況
id FirstAndThirdPartyAudience.firstAndThirdPartyAudienceId フィールド。
name FirstAndThirdPartyAudience.displayName フィールド。
data_partner_id 利用できません。
accessing_advertisers 利用できません。
partner_pricing 利用できません。
advertiser_pricings 利用できません。