エンティティ読み込みファイル（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 が分離され、Display & Video 360 API との整合性がさらに高まりました。詳細については、v7 移行ガイドとリファレンス ドキュメントをご覧ください。
限定公開リソース
ERF プライベート テーブルには、パートナーが所有するプライベート リソースの現在の設定の日次スナップショットが提供されます。1 つのパートナーで作成できるリソースの量が非常に多いため、これらのファイルは非常に大きくなり、ダウンロードと処理が困難になる可能性があります。
API では、各非公開テーブルには、そのリソースタイプの取得と管理のためのエンドポイントを提供する対応するサービスがあります。リソースは、各サービスのリストメソッドを使用して一括取得できます。API では、各リソースの JSON 構造が ERF と異なり、異なるフィールド名と共有リソースが使用されます。
リソースの ERF 表現で利用可能な特定の情報（リソースの割り当てられたターゲティング設定やチャンネルのサイトなど）は、API では元のリソースの子として表され、追加の API リクエストで取得する必要があります。
API でのエンティティの取得
ディスプレイ＆ビデオ 360 のリソースは、直接の API リクエストまたは BigQuery への自動インポートで取得できます。
直接 API リクエスト
各リソースタイプは、異なる API サービスを使用して取得できます。リソースは、適切なサービスの get メソッドまたは list メソッドを使用して、個別または一括で取得できます。Display & Video 360 API のリスト メソッドの重要なプロパティには、次のようなものがあります。
- 必要なスコープ。パートナーでスコープが設定される 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 回確認する必要があります。
ディスプレイ＆ビデオ 360 API に効率的にアクセスする方法については、割り当て最適化ガイドをご覧ください。
BigQuery にインポートする
ディスプレイ＆ビデオ 360 API BigQuery コネクタを使用すると、ディスプレイ＆ビデオ 360 のリソース構成を毎日 BigQuery に直接自動的にインポートできます。構成は、ディスプレイ＆ビデオ 360 API リソース設計を使用して BigQuery に保存されます。API リソースのサブセットがサポートされています。
Display & Video 360 API BigQuery コネクタの使用方法については、次の Cloud ドキュメントをご覧ください。
既知の API データのギャップ
ERF から Display & Video 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 を費用から除外するには、DV360 ヘルプセンターの手順に沿って操作してください。
非公開テーブルのフィールド マッピング
以下の表に、ERF 非公開テーブルのフィールドと、ディスプレイ＆ビデオ 360 API の既存のフィールドまたはサービスとの対応を示します。1 つのフィールドの値が別のフィールドにマッピングされる場合でも、同じデータ型、列挙型の値、ID 空間を使用するとは限りません。
広告主
キャンペーン
| 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 | 利用不可 |
| 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
フィールド。
|
| 説明 | 利用できません。 |
| 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 | 利用できません。 |
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
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
ディスプレイ＆ビデオ 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 |
FirstPartyAndPartnerAudience.firstPartyAndPartnerAudienceId
フィールド。
|
| name |
FirstPartyAndPartnerAudience.displayName
フィールド。
|
| data_partner_id | 利用できません。 |
| accessing_advertisers | 利用できません。 |
| partner_pricing | 利用できません。 |
| advertiser_pricings | 利用できません。 |