实体读取文件 (ERF) 是合作伙伴广告系列对象的 JSON 表示形式，系统应根据请求每天生成这些对象，并通过 Google Cloud Storage 提供这些对象。
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 使用与 ERF 不同的 JSON 结构来表示相同的资源类型。某些资源（如公开定位设置）可能会使用不同的 ID 空间。
- 检索方法。与 ERF 提供的原始 JSON 文件不同，Display & Video 360 API 仅支持通过分页列表或通过 BigQuery 数据传输单独检索资源。
- 作用域。与按合作伙伴 ID 限定范围的 ERF 相反，大多数 API 资源都按广告客户 ID 设定范围。响应中包含的资源仅限于该范围内的资源。
API 中的 ERF 数据表示法
实体读取文件分为“公开”表和“不公开”表。公开表提供对所有用户均可用且适用的信息，例如定位值。不公开表格可提供合作伙伴特有的数据，例如广告素材或订单项资源。
Display & Video 360 API 不会使用这种二元分类，而是让所有这些信息均可通过各种服务和使用不同的 JSON 结构检索。本节将通过公开和私有 ERF 表提供的信息与通过 Display & Video 360 API 资源和服务提供的信息进行比较。
公开信息
在解读检索到的私有资源的定位设置以及通过通过界面上传的部分结构化数据文件 (SDF) 版本分配定位条件时，ERF 公开表可为用户提供参考资料。这些参考资料对所有用户而言都是相同的，其中包含用于映射的数字 ID 和更具描述性的详细信息（例如显示名称）。
使用 Display & Video 360 API 时，可通过 targetingTypes.targetingOptions 服务检索定位参考信息。与公共表格类似，此服务可提供特定定位类型的定位选项的 ID 和详细信息。请参阅我们现有的设置定位条件页面，通过其中的代码示例了解如何检索定位条件选项 ID。
公开表和 SDF
在 SDF v7 之前，实体读取文件和结构化数据文件使用相同的 ID 空间进行定位设置。如果您是使用 ERF 公开表格通过 SDF 解读或分配定位设置的 SDF 用户，则可以通过 Display & Video 360 界面以 CSV 格式下载此参考资料。
从 v7 开始，我们更新了结构化数据文件部分列使用的 ID 空间，以便将 SDF 与 ERF 分离开来，并进一步与 Display & Video 360 API 保持一致。如需了解详情，请参阅 v7 迁移指南和参考文档。
私有资源
ERF 私有表可提供合作伙伴拥有的私有资源的当前设置的每日快照。由于单个合作伙伴可以创建大量资源，因此这些文件可能会变得非常大，难以下载和处理。
在 API 中，每个专用表都有相应的服务，这些服务提供用于检索和管理该资源类型的端点。您可以使用每项服务各自的 list 方法批量检索资源。与 ERF 相比，API 中每个资源的 JSON 结构也不同，使用的是不同的字段名称和共享资源。
某些信息在资源的 ERF 表示法中可用，例如资源的分配的定位设置或渠道的网站，在 API 中表示为原始资源的子资源，必须通过其他 API 请求检索。
API 中的实体检索
Display & Video 360 资源可通过直接 API 请求进行检索，也可自动导入到 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 界面检索。
- 资源字段的子集。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 |
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
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 | 不可用。 |