從實體讀取檔案遷移

實體讀取檔案 (ERF) 是合作夥伴的廣告活動物件 JSON 表示法，這些物件每天都會產生，並透過 Google Cloud Storage 提供。

ERF 已於 2021 年 6 月淘汰。ERF 將於 2024 年 10 月 31 日正式停用，不再產生。我們建議所有現有的實體讀取檔案使用者都遷移至 Display & Video 360 API，以便繼續擷取 Display & Video 360 資源。

本指南將說明如何透過以下方式，從實體讀取檔案遷移至 Display & Video 360 API：

  • 概略說明兩個介面之間的差異
  • 比較 ERF 資料表與 API 服務
  • 提供透過 API 擷取實體的指引
  • 確認現有的資料落差
  • 顯示所有 ERF 欄位與可比較的 API 資源欄位的對應關係

總覽

從 ERF 遷移至 Display & Video 360 API 時，請考量以下幾項主要差異：

  • 資料更新間隔：ERF 每天都會產生，但 API 會擷取資源的最新版本。
  • 資源結構。API 使用與 ERF 不同的 JSON 結構來表示相同的資源類型。部分資源 (例如公開指定目標設定) 可能會使用不同的 ID 空間。
  • 擷取方法：Display & Video 360 API 只能擷取個別資源、分頁清單或透過 BigQuery 資料移轉擷取資源，而擷取的資源與 ERF 提供的原始 JSON 檔案有所不同。
  • 範圍。與以合作夥伴 ID 限定範圍的 ERF 不同，大部分的 API 資源都是依據廣告主 ID 限定範圍。回應中包含的資源僅限於該範圍內的資源。

API 中的 ERF 資料表示法

實體讀取檔案分成「公開」和「不公開」表格。公開表格提供所有使用者都能使用的資訊，例如指定值。私人資料表提供合作夥伴專屬資料，例如廣告素材或委刊項資源。

Display & Video 360 API 不會使用這項字典，而是透過各種服務並使用不同的 JSON 結構擷取所有資訊。本節會比較透過公開和私人 ERF 資料表提供的資訊，以及透過 Display & Video 360 API 資源與服務提供的資訊。

公開資訊

ERF 公開資料表提供參考資料，可用於解讀擷取私人資源的指定目標設定，以及透過透過 UI 上傳的部分結構化資料檔案 (SDF) 版本指派指定目標。所有使用者都能使用相同的參考資料，其中包含用於對應的數字 ID，以及更多描述性的詳細資料 (例如顯示名稱)。

使用 Display & Video 360 API 時，您可以透過 targetingTypes.targetingOptions 服務擷取指定目標參考資料。與公開表格類似，這項服務為特定指定類型提供指定目標選項的 ID 和詳細資料。請參閱現有的「設定指定目標」頁面，取得指定目標選項 ID 擷取功能的程式碼範例。

公開表格和 SDF

在 SDF 第 7 版之前，實體讀取檔案和結構化資料檔案會使用相同的 ID 空間進行指定目標設定。如果您是 SDF 使用者，而使用 ERF 公開資料表用 SDF 解讀或指派指定目標設定，可以改為透過 Display & Video 360 UI，下載此 CSV 格式的參考資料。

自第 7 版起，部分結構化資料檔案欄使用的 ID 空間已更新為將 SDF 與 ERF 分開，並進一步與 Display & Video 360 API 保持一致。詳情請參閱 v7 遷移指南和參考說明文件。

私人資源

ERF 私人資料表：針對合作夥伴擁有的私人資源目前設定提供每日快照。由於單一合作夥伴可建立大量資源，因此這些檔案可能會變得非常龐大，而且難以下載和處理。

在 API 中，每個私人資料表都有對應的服務，可提供用於擷取及管理該資源類型的端點。您可以使用每項服務各自的 list 方法大量擷取資源。與 ERF 相比，每項資源的 JSON 結構在 API 中並不相同，且使用不同的欄位名稱及共用資源。

在資源的 ERF 表示法中，某些特定資訊 (例如資源的指派的指定目標設定或管道的網站) 會以原始資源的子項表示，並且必須透過其他 API 要求才能擷取。

API 中的實體擷取

您可以直接透過 API 要求擷取 Display & Video 360 資源，也可以自動將資源匯入 BigQuery。

直接 API 要求

每個資源類型可透過不同的 API 服務擷取。您可使用適當的服務的 get 或 list 方法，分別擷取或大量擷取資源。Display & Video 360 API 清單方法的重要屬性包括：

  • 必要範圍。與 ERF 不同，ERF 以合作夥伴界定範圍，但在 API 中大部分的資源都是由「廣告客戶」限定。如要擷取合作夥伴底下的所有資源類型 (例如委刊項)，可能需要為該合作夥伴的每個子項廣告主提出個別的清單要求。例外狀況包括合作夥伴的直接子項，例如廣告主和合作夥伴自有的頻道。
  • 分頁。API 清單方法會使用分頁機制，確保回應在合理大小內，將多數個別要求回應或頁面限制為 100 項資源。如果相關資源的數量大於頁面大小，系統就必須連續呼叫清單呼叫，才能擷取完整清單回應的後續頁面。如需列出清單回應分頁的程式碼範例，請參閱「指定目標指南」頁面的某個章節，有關擷取可用的指定目標選項 。
  • 指定擷取目標所需的額外要求。資源的指定目標設定不包含在其 API JSON 物件中，而會改為子項資源稱為「指派的指定目標選項」。這些子資源必須透過個別要求擷取。舉例來說，對於透過 advertisers.lineItems.list 要求擷取的每個委刊項，系統都必須個別發出 advertisers.lineItems.bulkListAssignedTargetingOptions 要求，才能擷取所有指定目標資訊。

最佳化資源擷取

Display & Video 360 API 可能需要多項要求，才能擷取單一實體讀取檔案中的相同數量資訊。最佳化擷取資源的方式可協助您更有效率地擷取資料：

  • 對 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 連接器可讓您每天自動將 Display & Video 360 資源設定匯入 BigQuery。這些設定會透過 Display & Video 360 API 資源設計儲存在 BigQuery 中。系統支援部分 API 資源。

如要進一步瞭解如何使用 Display & Video 360 API BigQuery 連接器，請參閱下列雲端說明文件：

已知的 API 資料缺口

從 ERF 遷移至 Display & Video 360 API 時，您可能會遇到明顯的資料落差，例如：

  • 故事廣告訂單：故事廣告訂單無法透過 API 擷取，只能透過 Display & Video 360 UI 擷取。
  • 資源欄位的子集。透過 Display & Video 360 API 擷取的相應資源中，缺少 ERF 物件中的少數資源欄位無法使用。

附錄：將 ERF 欄位對應至 API

公開資料表對應關係

下表將 ERF 公開表格的欄位對應至 Display & Video 360 API 中的現有指定類型和指定目標選項欄位。雖然某個欄位的值可能會對應至另一個欄位，但無法保證這些欄位使用相同的資料類型、列舉值或 ID 空間。

應用程式組合

可在指定類型「TARGETING_TYPE_APP_CATEGORY」下擷取。

ERF 欄位名稱DV360 API 適用情形
id TargetingOption.targetingOptionId 欄位中。
名稱 TargetingOption.appCategoryDetails.displayName 欄位中。

瀏覽器

可在指定類型TARGETING_TYPE_BROWSER下擷取。

ERF 欄位名稱DV360 API 適用情形
id TargetingOption.targetingOptionId 欄位中。
is_mobile 不適用。
名稱 TargetingOption.browserDetails.displayName 欄位中。

DataPartner

Display & Video 360 API 中沒有對等的資源或欄位。

DeviceCriteria

可在指定類型 TARGETING_TYPE_OPERATING_SYSTEM、TARGETING_TYPE_DEVICE_MAKE_MODEL 和 TARGETING_TYPE_DEVICE_TYPE 下擷取。

ERF 欄位名稱DV360 API 適用情形
id TargetingOption.targetingOptionId 欄位或 DeviceType 列舉。
is_mobile 不適用。
名稱 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 欄位名稱DV360 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 欄位名稱DV360 API 適用情形
id TargetingOption.targetingOptionId 欄位中。
is_mobile 不適用。
名稱 TargetingOption.carrierAndIspDetails.displayName 欄位中。
secondary_criteria_id TargetingOption.targetingOptionId 欄位中。

語言

可在指定類型TARGETING_TYPE_LANGUAGE下擷取。

ERF 欄位名稱DV360 API 適用情形
id TargetingOption.targetingOptionId 欄位中。
名稱 不適用。您可以在 TargetingOption.languageDetails.displayName 欄位中查看語言的完整顯示名稱。

SiteToPlacementId

Display & Video 360 API 中沒有對等的資源或欄位。

SupportedExchange

可在指定類型TARGETING_TYPE_EXCHANGE下擷取。

ERF 欄位名稱DV360 API 適用情形
id Exchange 列舉。
名稱 Exchange 列舉。

UniversalSite

Display & Video 360 API 中沒有對等的資源或欄位。個別網站和應用程式可分別在指定類型 TARGETING_TYPE_URL 和 TARGETING_TYPE_APP 底下指定。在 Display & Video 360 中，您可以指定任何應用程式或網址，但不能針對所有應用程式或網址製作報表。如要從支出中移除無法列入報表的應用程式和網址，請按照 DV360 說明中心的指示操作。

私人資料表欄位對應

下表將 ERF 私人資料表的欄位對應至 Display & Video 360 API 中的現有欄位或服務。雖然一個欄位的值可能會對應至另一個欄位，但無法保證這些欄位使用相同的資料類型、列舉值或 ID 空間。

Advertiser [廣告客戶]

ERF 欄位名稱DV360 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 欄位中會列出共用 CM360 Floodlight 設定的 CM360 廣告主 ID。
dcm_floodlight_group_id Advertiser.adServerConfig.cmHybridConfig.cmFloodlightConfigId 欄位中。
dcm_syncable_site_ids Advertiser.adServerConfig.cmHybridConfig.cmSyncableSiteIds 欄位中。
enable_oba_tags 不適用。

Campaign

ERF 欄位名稱DV360 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 欄位名稱DV360 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 欄位名稱DV360 API 適用情形
id CustomList.customListId 欄位中。
名稱 CustomList.displayName 欄位中。
description 不適用。
advertiser_id 不適用。

FloodlightActivity

ERF 欄位名稱DV360 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 欄位名稱DV360 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 欄位名稱DV360 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 欄位名稱DV360 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 欄位名稱DV360 API 適用情形
id NegativeKeywordList.negativeKeywordListId 欄位中。
名稱 NegativeKeywordList.displayName 欄位中。
advertiser_id NegativeKeywordList.advertiserId 欄位中。

Partner

ERF 欄位名稱DV360 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 不適用。

Pixel

Display & Video 360 API 中沒有對等的資源或欄位。

UniversalChannel

ERF 欄位名稱DV360 API 適用情形
id Channel.channelId 欄位中。
名稱 Channel.displayName 欄位中。
site_ids 視 owner 的類型而定，您可以透過 advertisers.channels.sites.list 和 partners.channels.sites.list 方法擷取。
accessing_advertisers 不適用。
is_deleted 不適用。
is_brand_safe_channel 不適用。

UserList

ERF 欄位名稱DV360 API 適用情形
id FirstAndThirdPartyAudience.firstAndThirdPartyAudienceId 欄位中。
名稱 FirstAndThirdPartyAudience.displayName 欄位中。
data_partner_id 不適用。
accessing_advertisers 不適用。
partner_pricing 不適用。
advertiser_pricings 不適用。