エンティティ読み込みファイル（ERF）はパートナーのキャンペーン オブジェクトの JSON 表現です。リクエストに応じて毎日生成され、Google Cloud Storage で利用可能になります。
ERF は 2021 年 6 月に非推奨となりました。2024 年 10 月 31 日以降、ERF は正式に廃止され、生成されなくなります。エンティティ読み取りファイルを使用している既存のユーザーはすべて、引き続きディスプレイ &ビデオ 360 リソースを取得するために、Display & Video 360 API に移行することをおすすめします。
このガイドでは、エンティティ読み込みファイルから Display & Video 360 API に以下の方法で移行する方法について説明します。
- 2 つのインターフェースの違いの概要
- ERF テーブルと API サービスの比較
- API を介したエンティティ取得のガイダンスの提供
- 既存のデータのギャップを認識する
- すべての ERF フィールドと同等の API リソース フィールドのマッピングを提示
概要
ERF から Display & Video 360 API に移行する際には、考慮すべき主な相違点がいくつかあります。
- データの更新頻度。ERF は、API がリソースの最新バージョンを取得している間に毎日、一括で生成されます。
- リソース構造。この API は、ERF とは異なる JSON 構造を使用して同じリソースタイプを表します。一般公開ターゲティング設定などの一部のリソースでは、異なる ID 空間を使用する場合があります。
- 取得方法。ERF で提供される未加工の JSON ファイルとは異なり、Display & Video 360 API では、ページ分けされたリストや BigQuery データ転送を介したリソースを個別に取得する必要があります。
- 範囲。パートナー ID でスコープが設定される ERF とは対照的に、ほとんどの API リソースのスコープは広告主 ID で設定されます。レスポンスに含まれるリソースは、そのスコープ内のリソースに制限されます。
API での ERF データ表現
エンティティ読み込みファイルは「公開」テーブルと「非公開」テーブルに分かれています。一般公開テーブルは、ターゲティング値など、すべてのユーザーが利用可能で適用できる情報を提供します。非公開テーブルは、クリエイティブや広告申込情報のリソースなど、パートナーに固有のデータを提供します。
Display & Video 360 API は、このような二分法を使用しません。代わりに、さまざまなサービスを介してさまざまな JSON 構造を使用して、これらの情報をすべて取得できるようにします。このセクションでは、一般公開 ERF テーブルと限定公開 ERF テーブルから取得される情報と、Display & Video 360 API リソースおよびサービスから取得される情報を比較します。
公開情報
ERF 一般公開テーブルは、取得したプライベート リソースのターゲット設定を解釈し、UI を通じてアップロードした構造化データファイル（SDF）バージョンのサブセットを使用してターゲティングを割り当てる際に使用できる参考資料です。これらの参考資料は、すべてのユーザーが同じ内容で、マッピングに使用される数値 ID と、表示名などのわかりやすい詳細情報で構成されています。
Display & Video 360 API を使用している場合、ターゲティングの参照情報は targetingTypes.targetingOptions サービスから取得できます。一般公開テーブルと同様に、このサービスでは特定のターゲティング タイプのターゲティング オプションの ID と詳細が提供されます。ターゲティング オプション ID を取得するコード例については、既存のターゲティングの設定ページをご覧ください。
一般公開テーブルと SDF
SDF v7 より前は、エンティティ読み込みファイルと構造化データファイルでは、ターゲット設定に同じ ID 空間が使用されます。ERF 一般公開テーブルを使用して、SDF でターゲット設定を解釈または割り当てている SDF をご利用の場合は、代わりにディスプレイ &ビデオ 360 の管理画面から CSV 形式でこの参照マテリアルをダウンロードできます。
v7 以降で、構造化データファイル列のサブセットで使用される ID 空間が更新され、SDF と ERF が分離され、Display & Video 360 API との整合性が高まりました。詳細については、v7 移行ガイドとリファレンス ドキュメントをご覧ください。
プライベート リソース
ERF プライベート テーブルは、パートナーが所有するプライベート リソースの現在の設定の日次スナップショットを提供します。1 つのパートナーの下で作成できるリソースの量は膨大であるため、これらのファイルは非常に大きくなり、ダウンロードと処理が難しくなる可能性があります。
API では、各プライベート テーブルには、そのリソースタイプの取得と管理用のエンドポイントを提供する対応するサービスがあります。リソースは、各サービスの list メソッドを使用して一括で取得できます。各リソースの JSON 構造は、API と 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リクエストを実行して、すべてのターゲティング情報を取得する必要があります。
リソース取得を最適化する
Display & Video 360 API では、1 つのエンティティ読み取りファイルで取得できる情報と同じ量の情報を取得するために、複数のリクエストが必要になる場合があります。リソースの取得方法を最適化することで、必要なデータをより効率的に取得できます。
- API に同時リクエストを行う。Display & Video 360 API は、プロジェクトごとの広告主あたりのリクエスト数のレート制限を使用して、インフラストラクチャを保護します。この割り当て構造により、複数の広告主にマルチスレッド ソリューションを実装して、必要なすべてのリソースの取得にかかる合計時間を短縮できます。ページ分割では、特定のスコープ内の型のリソースはすべて連続呼び出しで取得する必要がありますが、別のスコープ内または別の型のリソースの取得は同時に実行できます。
- リスト呼び出しでフィルタを使用し、パラメータで並べ替えて、関連するリソースのみを取得します。たとえば、前日更新された広告申込情報のみを取得したい場合は、
advertisers.lineItems.listメソッドのfilterパラメータを使用して、指定されたタイムスタンプよりもupdateTimeが大きい広告申込情報のみを返すことができます。これにより、必要なリクエストの数を大幅に削減できます。 - 定期的に使用する ID をキャッシュに保存して、不要な API リクエストを回避します。ターゲティング オプション ID や Google オーディエンス ID などの特定の参照情報は比較的安定しているため、安全に保存できるため、使用のたびに取得する必要がなくなります。ただし、頻度の低い変更や非推奨に対応するために、キャッシュに保存された値を毎週確認する必要があります。
Display & Video 360 API に効率的にアクセスする方法について詳しくは、割り当ての最適化ガイドをご覧ください。
BigQuery にインポートする
Display & Video 360 API BigQuery Connector を使用すると、ディスプレイ &ビデオ 360 のリソース構成を BigQuery に毎日自動的にインポートできます。構成は、Display & Video 360 API リソース設計を使用して BigQuery に保存されます。API リソースのサブセットがサポートされています。
Display & Video 360 API BigQuery Connector の使用方法については、次のクラウドのドキュメントをご覧ください。
既知の API データのギャップ
ERF から Display & Video 360 API に移行すると、次のような顕著なデータギャップが発生する場合があります。
- ストーリーの広告掲載オーダーストーリー広告掲載オーダーは API では取得できず、ディスプレイ &ビデオ 360 の管理画面で取得する必要があります。
- リソース フィールドのサブセット。ERF オブジェクトに含まれる少数のリソース フィールドは、Display & Video 360 API で取得された対応するリソースでは使用できません。
付録: ERF フィールドと API のマッピング
一般公開テーブルのマッピング
次の表は、ERF 一般公開テーブルのフィールドを、Display & Video 360 API の既存のターゲティング タイプおよびターゲティング オプションのフィールドと対応表したものです。あるフィールドの値が別のフィールドの値にマッピングされても、同じデータ型、列挙値、または 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
Display & Video 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
Display & Video 360 API には、対応するリソースやフィールドはありません。
SupportedExchange
ターゲティング タイプ TARGETING_TYPE_EXCHANGE で取得できます。
| ERF フィールド名 | ディスプレイ&ビデオ 360 API の対応状況 |
|---|---|
| id |
Exchange
列挙型。
|
| name |
Exchange
列挙型。
|
UniversalSite
Display & Video 360 API には、対応するリソースやフィールドはありません。個々のサイトとアプリは、それぞれ TARGETING_TYPE_URL と TARGETING_TYPE_APP のターゲティング タイプで直接ターゲットに設定できます。ディスプレイ &ビデオ 360 ではどのアプリや URL でもターゲットに設定できますが、すべてのアプリまたは URL をレポートできるわけではありません。レポート対象外のアプリや URL を費用から除外する場合は、ディスプレイ&ビデオ 360 ヘルプセンターの手順に沿ってください。
プライベート テーブルのフィールド マッピング
次の表は、ERF 非公開テーブルのフィールドを、Display & Video 360 API の既存のフィールドやサービスに対応付けしたものです。あるフィールドの値は別のフィールドの値にマッピングできますが、同じデータ型、列挙値、または ID 空間を使用する保証はありません。
Advertiser
Campaign
| 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
フィールド。
|
| budget |
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
フィールド。
|
| metric |
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
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 | 利用できません。 |