实体读取文件 (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 中，每个私有表都有对应的服务，该服务会提供用于检索和管理该资源类型的端点。您可以使用每项服务的相应列表方法批量检索资源。与 ERF 相比，API 中每个资源的 JSON 结构不同，使用不同的字段名称和共享资源。
资源的 ERF 表示法中提供的某些信息（例如资源的分配的定位设置或渠道的网站）在 API 中表示为原始资源的子项，并且必须通过其他 API 请求检索。
API 中的实体检索
您可以通过直接 API 请求检索 Display & Video 360 资源，也可以将其自动导入 BigQuery。
直接 API 请求
您可以通过不同的 API 服务检索每种资源类型。您可以分别使用相应服务的 get 或 list 方法逐个或批量检索资源。Display & Video 360 API 列表方法的重要属性包括：
- 必需的范围。与 partner（合作伙伴）级范围的 ERF 不同，API 中的大多数资源都采用 advertiser（广告客户）级范围。若要检索某个合作伙伴名下某种资源类型（例如订单项）的所有资源，可能需要针对该合作伙伴的每个子级广告客户发出单独的列表请求。例外情况包括合作伙伴的直接子级，例如广告客户和合作伙伴自有频道。
- 分页。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
字段。
|
| 名称 |
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 |
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 | 不可用 |
| 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 | 不可用。 |
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
字段。
|
| 名称 |
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
字段。
|
| 名称 |
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 |
FirstPartyAndPartnerAudience.firstPartyAndPartnerAudienceId
字段。
|
| 名称 |
FirstPartyAndPartnerAudience.displayName
字段。
|
| data_partner_id | 不可用。 |
| accessing_advertisers | 不可用。 |
| partner_pricing | 不可用。 |
| advertiser_pricings | 不可用。 |