从 v1 迁移到 v2

上次更新时间：2022 年 12 月 6 日

迁移应用

从 v1 迁移到 v2 需要更新端点网址以调用 v2，并更新应用以考虑破坏性更改。

将 API 调用从 v1 更新为 v2

如需使用 v2 而非 v1，您需要更新请求以使用新的 v2 端点。

例如，如需使用 v1 调用 advertisers.get 方法，您可以使用以下网址：

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

对于 v2，请将网址更新为以下网址：

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

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

进行所需的更改

我们将在 v2 中引入多项破坏性更改。请查看以下说明，并根据您当前对 Display & Video 360 API 的使用情况进行必要的更改。

更新了对定位方法的调用

• 现在，某些定位类型是使用枚举值（而非定位选项 ID）进行分配的。例如，现在，系统会使用 DEVICE_TYPE_TABLET DeviceType 枚举（而非 targetingTypes.targetingOptions 服务中的定位选项 ID）直接定位到平板电脑设备。这些枚举的字符串版本在这些 AssignedTargetingOption 资源的新 assignedTargetingOptionIdAlias 字段中表示，可在检索或删除现有定位条件时使用。这些 AssignedTargetingOption 资源的 assignedTargetingOptionId 值没有更改。

  更新用于管理以下定位类型的调用，以使用枚举值：

  • TARGETING_TYPE_AGE_RANGE
  • TARGETING_TYPE_CONTENT_INSTREAM_POSITION
  • TARGETING_TYPE_CONTENT_OUTSTREAM_POSITION
  • TARGETING_TYPE_DEVICE_TYPE
  • TARGETING_TYPE_DIGITAL_CONTENT_LABEL_EXCLUSION
  • TARGETING_TYPE_ENVIRONMENT
  • TARGETING_TYPE_EXCHANGE
  • TARGETING_TYPE_GENDER
  • TARGETING_TYPE_HOUSEHOLD_INCOME
  • TARGETING_TYPE_NATIVE_CONTENT_POSITION
  • TARGETING_TYPE_OMID
  • TARGETING_TYPE_PARENTAL_STATUS
  • TARGETING_TYPE_SENSITIVE_CATEGORY_EXCLUSION
  • TARGETING_TYPE_VIDEO_PLAYER_SIZE
  • TARGETING_TYPE_VIEWABILITY

• 方法 advertisers.lineItems.bulkEditLineItemAssignedTargetingOptions 已被方法 advertisers.lineItems.bulkEditAssignedTargetingOptions 取代。

• 方法 advertisers.lineItems.bulkListLineItemAssignedTargetingOptions 已被方法 advertisers.lineItems.bulkListAssignedTargetingOptions 取代。

• 更新了用于管理 TARGETING_TYPE_PROXIMITY_LOCATION_LIST 的调用，以使用设定的半径大小和距离单位，而不是 ProximityRadiusRange 枚举值。

• 用于在单个父级资源下的多个定位类型中检索或修改定位选项的定位方法已重命名。

  更新对以下方法的调用，以使用其新名称：

  • 将 advertisers.bulkEditAdvertiserAssignedTargetingOptions 替换为 advertisers.editAssignedTargetingOptions
  • 将 advertisers.bulkListAdvertiserAssignedTargetingOptions 替换为 advertisers.listAssignedTargetingOptions
  • 将 advertisers.campaigns.bulkListCampaignAssignedTargetingOptions 替换为 advertisers.campaigns.listAssignedTargetingOptions
  • 将 advertisers.insertionOrders.bulkListInsertionOrderAssignedTargetingOptions 替换为 advertisers.insertionOrders.listAssignedTargetingOptions
  • 将 partners.bulkEditPartnerAssignedTargetingOptions 替换为 partners.editAssignedTargetingOptions

更新对 advertisers.lineItems 服务的调用

• inventorySourceIds 字段已移除。使用 TARGETING_TYPE_INVENTORY_SOURCE 的 AssignedTargetingOption 资源管理商品目录来源分配。

• 以下 LineItemWarningMessage 枚举值已在 v2 中废弃，并且不会再显示在 LineItem.warningMessages 中：

  • NO_POSITIVE_AUDIENCE_LIST_TARGETED
  • APP_INSTALL_NO_CONVERSION_PIXEL
  • TARGETING_REVOKED_OR_CLOSED_USER_LIST
  • APP_INSTALL_NO_OPTIMAL_BIDDING_STRATEGY
  • CREATIVE_SIZE_NOT_IN_USE_FOR_TARGETED_DEALS
  • NO_CREATIVE_FOR_TARGETED_DEALS
  • TARGETING_DEPRECATED_GEO_TARGET

• triggerId 字段已从 LineItemFlight 对象中移除，LINE_ITEM_FLIGHT_DATE_TYPE_TRIGGER 值已从 LineItemFlightDateType 枚举类型中移除。v2 不支持根据手动触发器的启用情况设置订单项支出。

更新对 customBiddingAlgorithms 服务的调用

customBiddingAlgorithmState 和 modelReadiness 字段已替换为 modelDetails 字段，该字段会为通过 CustomBiddingModelDetails 对象列表拥有访问权限的每个广告客户提供现有算法模型的就绪和暂停状态。

其他更改

除了上述破坏性更改之外，v2 还引入了新功能。

在首次发布后添加到 v2 中的功能可在版本说明中找到。

对 YouTube 订单项的只读权限

在 v2 中，您可以分别使用 advertisers.lineItems 和 advertisers.lineItems.targetingTypes.assignedTargetingOptions 服务检索 YouTube 订单项及其定位设置。该 API 提供只读访问权限，这意味着对这些订单项发出的任何写入请求都会返回错误。YouTube 订单项将采用以下 LineItemType 值之一：

• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_ACTION
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_AUDIO
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_NON_SKIPPABLE
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_NON_SKIPPABLE_OVER_THE_TOP
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_REACH
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_REACH_OVER_THE_TOP
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_SIMPLE
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_SIMPLE_OVER_THE_TOP
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_VIDEO_SEQUENCE

可提升性能的新方法

在 v2 中，advertisers.lineItems 服务提供了可替代批量请求的新方法，以便提高性能并减少配额消耗：

• 您可以使用 advertisers.lineItems.bulkUpdate 为多个订单项设置相同的字段值。目前仅支持更新 entityStatus 字段。
• 您可以使用 advertisers.lineItems.bulkEditAssignedTargetingOptions 在多个订单项中添加或移除相同的指定定位选项。
• 您可以使用 advertisers.lineItems.bulkListAssignedTargetingOptions 列出多个订单项中分配的定位选项。
• 您可以使用 advertisers.lineItems.duplicate 在同一广告订单中复制现有订单项，并复制所有配置和定位设置。

对广告订单定位条件的部分写入权限

在 v2 中，您可以使用 advertisers.insertionOrders.targetingTypes.assignedTargetingOptions 服务中的新 create 和 delete 方法修改 InsertionOrder 资源的部分定位设置。以下定位类型可在广告订单一级进行全面管理：

• TARGETING_TYPE_AGE_RANGE
• TARGETING_TYPE_BROWSER
• TARGETING_TYPE_CATEGORY
• TARGETING_TYPE_CHANNEL
• TARGETING_TYPE_DEVICE_MAKE_MODEL
• TARGETING_TYPE_DIGITAL_CONTENT_LABEL_EXCLUSION
• TARGETING_TYPE_ENVIRONMENT
• TARGETING_TYPE_GENDER
• TARGETING_TYPE_KEYWORD
• TARGETING_TYPE_LANGUAGE
• TARGETING_TYPE_NEGATIVE_KEYWORD_LIST
• TARGETING_TYPE_OPERATING_SYSTEM
• TARGETING_TYPE_PARENTAL_STATUS
• TARGETING_TYPE_SENSITIVE_CATEGORY_EXCLUSION
• TARGETING_TYPE_VIEWABILITY