从实体读取文件迁移

实体读取文件 (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 时，需要考虑一些关键差异，包括：

  • 数据新鲜度。ERF 每天都会批量生成，而 API 会检索资源的最新版本。
  • 资源结构。该 API 使用的 JSON 结构与 ERF 不同，但用于表示相同的资源类型。某些资源（例如公开定位设置）可能会使用不同的 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 v7 之前，实体读取文件和结构化数据文件使用相同的 ID 空间来设置定位条件。如果您是 SDF 用户，并使用 ERF 公共表格来解读或分配使用 SDF 的定位设置，则可以改为通过 Display & Video 360 界面以 CSV 格式下载此参考资料。

从 v7 开始，部分结构化数据文件列使用的 ID 空间已更新，以将 SDF 与 ERF 分离，并进一步与 Display & Video 360 API 保持一致。如需了解详情，请参阅 v7 迁移指南和参考文档。

私有资源

ERF 私有表会提供合作伙伴拥有的私有资源的当前设置的每日快照。由于单个合作伙伴可以创建的资源数量非常庞大，因此这些文件可能会变得非常大，难以下载和处理。

在该 API 中，每个私有表都有对应的服务，该服务会提供端点来检索和管理该资源类型。您可以使用每项服务各自的 list 方法批量检索资源。与 ERF 相比，API 中每个资源的 JSON 结构不同，使用不同的字段名称和共享资源。

资源的 ERF 表示法中提供的某些信息（例如资源的分配的定位设置或渠道的网站）在 API 中表示为原始资源的子项，并且必须通过其他 API 请求检索。

API 中的实体检索

您可以通过直接 API 请求检索 Display & Video 360 资源，也可以将其自动导入 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 连接器，请参阅以下 Cloud 文档：

已知的 API 数据缺口

从 ERF 迁移到 Display & Video 360 API 时，您可能会遇到一些明显的数据缺口，例如：

  • 故事广告订单。无法通过 API 检索故事广告订单，必须通过 Display & Video 360 界面检索。
  • 部分资源字段。ERF 对象中存在少数资源字段，这些字段在通过 Display & Video 360 API 检索的相应资源中不可用。

附录：将 ERF 字段映射到 API

公共表映射

下表将 ERF 公共表中的字段映射到 Display & Video 360 API 中的现有定位类型和定位选项字段。虽然一个字段的值可能会映射到另一个字段，但这并不保证它们使用相同的数据类型、枚举值或 ID 空间。

应用合集

可在定位类型 TARGETING_TYPE_APP_CATEGORY 下检索。

ERF 字段名称DV360 API 可用性
id TargetingOption.targetingOptionId 字段。
name TargetingOption.appCategoryDetails.displayName 字段。

浏览器

可在定位类型 TARGETING_TYPE_BROWSER 下检索。

ERF 字段名称DV360 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 字段名称DV360 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 字段名称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 不可用。
name TargetingOption.carrierAndIspDetails.displayName 字段。
secondary_criteria_id TargetingOption.targetingOptionId 字段。

语言

可在定位类型 TARGETING_TYPE_LANGUAGE 下检索。

ERF 字段名称DV360 API 可用性
id TargetingOption.targetingOptionId 字段。
name 不可用。如需了解某种语言的完整显示名称，请参阅 TargetingOption.languageDetails.displayName 字段。

SiteToPlacementId

Display & Video 360 API 中没有等效的资源或字段。

SupportedExchange

可在定位类型 TARGETING_TYPE_EXCHANGE 下检索。

ERF 字段名称DV360 API 可用性
id Exchange 枚举。
name 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 字段。
name 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.budgetUnit 为 BUDGET_UNIT_CURRENCY ，则请 LineItem.budget.maxAmount 字段。
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 字段。
name NegativeKeywordList.displayName 字段。
advertiser_id NegativeKeywordList.advertiserId 字段。

合作伙伴

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 字段。
name 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 字段。
name FirstAndThirdPartyAudience.displayName 字段。
data_partner_id 不可用。
accessing_advertisers 不可用。
partner_pricing 不可用。
advertiser_pricings 不可用。