从 Display & Video 360 API v4 迁移到 v5

上次更新日期：2026 年 10 月 22 日

迁移您的应用

从 v4 迁移到 v5 需要更新端点网址以调用 v5，更新应用以应对破坏性更改，并查看可能对集成有益的所有新功能。

将 API 调用从 v4 更新为 v5

如需使用 v5 而不是 v4，您需要更新请求以使用新的 v5 端点。

例如，如需使用 v4 调用 advertisers.get 方法，请使用以下网址：

GET https://displayvideo.googleapis.com/v4/advertisers/advertiserId

对于 v5，请将网址更新为以下内容：

GET https://displayvideo.googleapis.com/v5/advertisers/advertiserId

如果您使用客户端库向 API 发出请求，请使用最新版本的客户端库，并更新配置以使用 v5。

进行所需的更改

Display & Video 360 API v5 引入了多项破坏性更改。请查看以下说明，并根据您对 Display & Video 360 API 的现有使用情况进行必要的更改。

如需查看 Display & Video 360 API v4 和 v5 之间的差异的详尽列表，请参阅版本说明。

更新广告资源来源检索和定位，以使用新的 ID 和类型

Display & Video 360 API v5 更改了广告资源来源交易和竞价包的检索和定位方式。

在 v4 中，使用 inventorySources 服务检索到的 InventorySource 资源既代表广告资源来源交易，也代表竞价包。交易和竞价包均使用 TARGETING_TYPE_INVENTORY_SOURCE 进行定位。

在 v5 中，广告资源来源交易和竞价包是分开处理的：

• 广告资源来源交易使用 TARGETING_TYPE_INVENTORY_SOURCE_DEAL 进行定位，使用 advertisers.inventorySources 和 partners.inventorySources 服务进行检索，并使用 AssignedTargetingOption 字段 inventorySourceDetails 进行定位。
• 竞价包使用 TARGETING_TYPE_AUCTION_PACKAGE 进行定位，使用 targetingTypes.targetingOptions 服务进行检索，并使用 AssignedTargetingOption 字段 auctionPackageDetails 进行定位。

此更新会更改现有交易和竞价包所用的 ID，因此您在迁移后无法使用任何之前缓存的 InventorySource 资源 ID。

除了这些变更之外，v5 还移除了创建、更新和修改广告资源来源访问函数的功能。

更新需求开发和 YouTube 资源的受众群体定位逻辑

Display & Video 360 API v5 更新了需求开发和 YouTube 资源的受众群体定位逻辑，以便为每个定位的受众群体名单使用单独的分配选项。

在 v4 中，所有受众群体定位均使用 TARGETING_TYPE_AUDIENCE_GROUP 进行管理。

在 v5 中，分配给需求开发广告组和 YouTube 广告组的受众群体定位是使用以下定位类型和 AssignedTargetingOption 资源字段之一进行管理的，具体取决于受众群体的类型：

• TARGETING_TYPE_COMBINED_AUDIENCE（使用 combinedAudienceDetails）
• TARGETING_TYPE_CUSTOM_LIST（使用 customListDetails）
• TARGETING_TYPE_FIRST_PARTY_AND_PARTNER_AUDIENCE使用 firstPartyAndPartnerAudienceDetails
• TARGETING_TYPE_GOOGLE_AUDIENCE（使用 googleAudienceDetails）
• TARGETING_TYPE_LOOKALIKE_AUDIENCE使用 lookalikeAudienceDetails

订单项将继续使用单个 TARGETING_TYPE_AUDIENCE_GROUP AssignedTargetingOption 来管理所有类型的受众群体定位。

升级到 Data Manager API，以便管理目标客户匹配受众群体

Display & Video 360 API v5 移除了以下方法，从而移除了创建和管理目标客户匹配受众群体成员的功能：

• firstPartyAndPartnerAudiences.create
• firstPartyAndPartnerAudiences.editCustomerMatchMembers
• firstPartyAndPartnerAudiences.patch

如需继续管理目标客户匹配受众群体，请升级您的工作流以使用 Data Manager API。

添加了对检索数字户外广告订单的支持

Display & Video 360 API v5 增加了对检索数字户外广告订单项的支持。

如果您的广告客户使用数字户外广告，请升级所有调用 advertisers.insertionOrders.list 的集成，以便纳入 insertionOrderType 字段值为 OUT_OF_HOME 的 InsertionOrder 资源。

在 v5 中，数字户外广告订单下的订单项将继续像在 v4 中一样可检索。

将对 Adloox 的引用更新为 Peer39

在 v5 中，引用 Display & Video 360 与 Adloox（也称为 Scope3）的第三方品牌适宜性集成的字段和枚举值已更新为 Peer39：

• ThirdPartyVerifierAssignedTargetingOptionDetails 字段 adloox 已被 peer39 替换。
• PartnerCostType 枚举值 PARTNER_COST_TYPE_ADLOOX 和 PARTNER_COST_TYPE_ADLOOX_PREBID 已替换为 PARTNER_COST_TYPE_PEER39 和 PARTNER_COST_TYPE_PEER39_PREBID。

更新 YouTube 订单项、广告组和广告的字段

在 v5 中，LineItem、AdGroup 和 AdGroupAd 资源中的各种字段已被移除或更新。请更新您的资源检索逻辑，以适应这些变化。

在 LineItem 资源中：

• YoutubeAndPartnersSettings 字段 relatedVideoIds 已被 relatedVideos 替换。

在 LineItem 和 AdGroup 资源中：

• TargetingExpansionConfig 字段 audienceExpansionSeedListExcluded 和 audienceExpansionLevel 已移除。

在 AdGroupAd 资源中：

• 添加了 containsSyntheticMedia 字段。
• AudioAd、CommonInStreamAttribute 和 VideoPerformanceAd 对象中的 trackingUrl 字段已拆分为两个字段：trackingUrl 和 userSpecifiedTrackingUrl，以区分用于跟踪的网址和用户指定的跟踪网址。

移除对已弃用枚举值的引用

在 v5 中，之前已弃用的枚举值已被完全移除。虽然在向 API 发出的请求中使用这些值会导致 v4 中出现错误，但此更改会从 v5 客户端库中移除对这些值的任何引用。在升级到 v5 时，代码中对这些已弃用值的任何引用都可能会导致错误。

具有受影响值的枚举类型包括 ContentRatingTier、GoogleAudienceType、SdfVersion 和 SensitiveCategory。如需查看所有已移除枚举值的详尽列表，请参阅我们的版本说明。

查看新功能

除了破坏性更改之外，v5 还引入了以下新功能：

• 在广告客户一级，针对定位类型 TARGETING_TYPE_YOUTUBE_VIDEO 和 TARGETING_TYPE_YOUTUBE_CHANNEL，全面管理 YouTube 视频和频道排除式定位。在 v4 中，此定位条件是只读的。
• 能够创建数字户外广告 InsertionOrder 资源。
• 通过添加 AdGroup 字段 adSource 和 creativeAssignments 以及 AdGroupAd 字段 parentCreativeId，支持广告组使用分配的广告素材生成广告。
• 能够创建和检索 LookalikeAudience 资源。
• AdGroupAd 资源中新增了 containsSyntheticMedia 字段。