展示广告和Video 360 API v2 已停用。使用展示广告和Video 360 API v3。如需查看 v2 到 v3 的迁移说明，请参阅我们的迁移指南。

此页面由 Cloud Translation API 翻译。

从实体读取文件迁移

实体读取文件 (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` 字段。

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` 字段。

SupportedExchange

可在定位类型 TARGETING_TYPE_EXCHANGE 下检索。

ERF 字段名称	DV360 API 可用性
id	`Exchange` 枚举。
name	`Exchange` 枚举。

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