從實體讀取檔案遷移

實體讀取檔案 (ERF) 是合作夥伴的廣告活動物件透過 Google Cloud Storage 提供的 JSON 表示法。

ERF 已於 2021 年 6 月淘汰，並於 2024 年 10 月 31 日停用。系統不再產生 ERF。使用 Display &Video 360 API 擷取 Display &Video 360 資源。

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

  • 概略說明兩個介面之間的差異
  • 比較 ERF 表格與 API 服務
  • 提供透過 API 擷取實體的指南
  • 承認現有資料缺口
  • 將所有 ERF 欄位與類似的 API 資源欄位對應

總覽

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

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

API 中的 ERF 資料表示法

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

Display & Video 360 API 不會使用這種二分法，而是透過各種服務和不同的 JSON 結構，讓您可以擷取所有這類資訊。本節將比較透過公開和私人 ERF 資料表提供的資訊，以及透過 Display & Video 360 API 資源和服務提供的資訊。

公開資訊

ERF 公開資料表提供參考資料，供使用者在解讀已擷取的私人資源的指定目標設定時使用，並透過透過使用者介面上傳的結構化資料檔案 (SDF) 子集版本指定指定目標。這些參考資料對所有使用者都相同，包括用於對應的數字 ID，以及顯示名稱等更具描述性的詳細資料。

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

公開資料表和 SDF

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

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

私人資源

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

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

資源的 ERF 表示法中提供的特定資訊 (例如資源的指定目標設定或頻道的網站) 會在 API 中以原始資源的子項表示，且必須透過額外的 API 要求擷取。

API 中的實體擷取

Display &Video 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 可能需要多次要求，才能擷取單一實體讀取檔案提供的相同資訊量。最佳化資源擷取方式有助於更有效率地擷取需要的資料：

  • 對 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 使用者介面擷取。
  • 資源欄位的子集。在透過 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 空間。

廣告主

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 不適用。

廣告活動

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 欄位。
說明 不適用。
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.budgetUnit 是 BUDGET_UNIT_IMPRESSIONS ，則使用 LineItem.budget.maxAmount 欄位。
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 可透過 advertisers.channels.sites.list 和 partners.channels.sites.list 方法擷取 (視 owner 的類型而定)。
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 不適用。