从 Bid Manager API v1.1 迁移到 v2

2022 年 3 月，我们发布了 Bid Manager API 版本 2。随着这个新版本的发布，我们计划尽快宣布 v1.1 的停用日期。我们建议您尽快开始从 v1.1 迁移到 v2。

迁移应用

从 v1.1 迁移到 v2 需要将端点网址更新为调用 v2，并更新应用以应对重大更改。

将您的 API 调用从 v1.1 更新为 v2

如需使用 v2 而不是 v1.1，您需要将请求更新为使用新的 v2 端点。

确定等效方法

为了将您的 API 调用从使用 v1.1 更新为使用 v2，您必须先确定 v2 中等效的 v1.1 方法。

所有服务和方法的以下名称在 v1.1 和 v2 之间略有不同：

• v1.1 中的 Queries 和 Reports 服务在 v2 中称为 queries 和 queries.reports。
• 方法已按如下方式在 v2 中重命名：

  v1.1 方法名称	等效的 v2 方法
  Queries.createquery	queries.create
  Queries.deletequery	queries.delete
  Queries.getquery	queries.get
  Queries.listqueries	queries.list
  Queries.runquery	queries.run
  Reports.listreports	queries.reports.list

更新为新端点

确定等效方法后，您需要更新请求。例如，如需使用 v1.1 调用 queries.getquery 方法，应使用以下网址：

https://www.googleapis.com/doubleclickbidmanager/v1.1/query/queryId

如需调用 v2 中的等效方法（称为 queries.get），请将网址更新为以下内容：

GET https://doubleclickbidmanager.googleapis.com/v2/queries/queryId

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

进行所需的更改

我们在 v2 中引入了一些破坏性更改。请查看以下说明，并根据您现有的 Bid Manager API 用法进行必要的更改。

更新对 queries 服务的调用

• Query 资源中最初由常规嵌套对象表示的以下字段已更改为使用以下对象类型：

  v1.1 字段	等效的 v2 对象类型
  metadata	QueryMetadata
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	PathQueryOptions
  params.options.pathQueryOptions.channelGrouping	ChannelGrouping
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	PathQueryOptionsFilter
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	PathQueryOptionsFilter
  schedule	QuerySchedule

• Query 资源中最初由常规列表对象表示的以下字段已更改为以下新对象类型的列表：

  v1.1 列表字段	v2 对象类型
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	Rule
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	DisjunctiveMatchStatement
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	EventFilter
  params.options.pathQueryOptions.pathFilters[]	PathFilter
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	EventFilter

• Query 资源中的以下字段最初由字符串表示，在 v2 中由枚举类型表示，并包含以下更改：
  • metadata.dataRange 的 v2 等效项现在使用 Range 枚举。在转换为此枚举时，值 PREVIOUS_HALF_MONTH 已被移除，值 TYPE_NOT_SUPPORTED 更改为 RANGE_UNSPECIFIED。
  • metadata.format 现在使用 Format 枚举。在转换为此枚举时，值 EXCEL_CSV 已被移除，并添加了值 FORMAT_UNSPECIFIED。
  • params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match 和 params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match 现在使用 Match 枚举。
  • params.options.pathQueryOptions.pathFilters[].pathMatchPosition 现在使用 PathMatchPosition 枚举。在转换为此枚举时，添加了值 PATH_MATCH_POSITION_UNSPECIFIED。
  • schedule.frequency 现在使用 Frequency 枚举。在转换为此枚举时，添加了值 FREQUENCY_UNSPECIFIED。
  • params.type 现在使用 ReportType 枚举。在转换为此枚举时，进行了以下更改：
  • 以下值已弃用：
    • TYPE_ACTIVE_GRP
    • TYPE_AUDIENCE_PERFORMANCE
    • TYPE_CLIENT_SAFE
    • TYPE_COMSCORE_VCE
    • TYPE_CROSS_FEE
    • TYPE_CROSS_PARTNER
    • TYPE_CROSS_PARTNER_THIRD_PARTY_DATA_PROVIDER
    • TYPE_ESTIMATED_CONVERSION
    • TYPE_FEE
    • TYPE_KEYWORD
    • TYPE_LINEAR_TV_SEARCH_LIFT
    • TYPE_NIELSEN_AUDIENCE_PROFILE
    • TYPE_NIELSEN_DAILY_REACH_BUILD
    • TYPE_NIELSEN_ONLINE_GLOBAL_MARKET
    • TYPE_PAGE_CATEGORY
    • TYPE_PETRA_NIELSEN_DAILY_REACH_BUILD
    • TYPE_PETRA_NIELSEN_ONLINE_GLOBAL_MARKET
    • TYPE_PIXEL_LOAD
    • TYPE_THIRD_PARTY_DATA_PROVIDER
    • TYPE_TRUEVIEW_IAR
    • TYPE_VERIFICATION
    • TYPE_YOUTUBE_VERTICAL
  • 其余值都已更新，以便在界面中更好地反映它们的等效值：

    v1.1 值	等效的 ReportType 值
    TYPE_NOT_SUPPORTED	REPORT_TYPE_UNSPECIFIED
    TYPE_GENERAL	STANDARD
    TYPE_INVENTORY_AVAILABILITY	INVENTORY_AVAILABILITY
    TYPE_AUDIENCE_COMPOSITION	AUDIENCE_COMPOSITION
    TYPE_ORDER_ID	FLOODLIGHT
    TYPE_TRUEVIEW	YOUTUBE
    TYPE_NIELSEN_SITE	GRP
    TYPE_PETRA_NIELSEN_AUDIENCE_PROFILE	YOUTUBE_PROGRAMMATIC_GUARANTEED
    TYPE_REACH_AND_FREQUENCY	REACH
    TYPE_REACH_AUDIENCE	UNIQUE_REACH_AUDIENCE
    TYPE_PATH	FULL_PATH
    TYPE_PATH_ATTRIBUTION	PATH_ATTRIBUTION

• 字段 metadata.dataRange、reportDataStartTimeMs 和 reportDataEndTimeMs 已替换为字段 range、customStartDate 和 customEndDate。新的日期字段使用 Date 对象，而不是自 Unix Epoch 以来的毫秒数。这些替换字段已移至 DataRange 对象，该对象已分配给 QueryMetadata 对象中的 dataRange 字段。
• 字段 schedule.startTimeMs 和 schedule.endTimeMs 已替换为 QuerySchedule 对象中的字段 startDate 和 endDate。新的日期字段使用 Date 对象，而不是自 Unix Epoch 以来的毫秒数。
• 字段 metadata.running、metadata.reportCount、metadata.googleCloudStoragePathForLatestReport、metadata.googleDrivePathForLatestReport 和 metadata.latestReportRunTimeMs 已被移除。您应改用 queries.reports.list 方法并将 orderBy 查询参数为“key.reportId desc”来检索有关查询最新生成的报告的信息，以确保请求首先列出最新的报告。
• 字段 kind、timezoneCode、metadata.locale、params.includeInviteData 和 schedule.nextRunMinuteOfDay 已被移除。
• 创建后，queries.create 不再自动运行查询，并且 asynchronous 查询参数已移除。请在 queries.create 后调用 queries.run，以针对新查询生成报告。
• queries.run 方法通过以下方式进行了更新：
  • asynchronous 查询参数已替换为 synchronous 查询参数。新查询参数采用反向逻辑进行操作，如果未指定，则被视为 false。因此，queries.run 在 v2 中默认以异步方式生成报告，而在 v1.1 中则以同步方式生成报告。
  • 请求正文已更新，移除了 timezoneCode 字段，并将 dataRange、reportDataStartTimeMs、reportDataEndTimeMs 字段替换为分配给 dataRange 字段的 DataRange 对象。
  • 该方法会返回生成的 Report 对象，而不是空的响应正文。
• 移除了 queries.list 响应正文中的 kind 字段。

更新对 reports 服务的调用

• Report 资源中最初由常规嵌套对象表示的以下字段已更改为使用以下对象类型：

  v1.1 字段	等效的 v2 对象类型
  key	ReportKey
  metadata	ReportMetadata
  metadata.status	ReportStatus
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	PathQueryOptions
  params.options.pathQueryOptions.channelGrouping	ChannelGrouping
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	PathQueryOptionsFilter
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	PathQueryOptionsFilter

• Report 资源中最初由常规列表对象表示的以下字段已更改为以下新对象类型的列表：

  v1.1 列表字段	v2 对象类型
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	Rule
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	DisjunctiveMatchStatement
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	EventFilter
  params.options.pathQueryOptions.pathFilters[]	PathFilter
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	EventFilter

• Report 资源中最初由字符串表示的以下字段已更改，因此它们在 v2 中的等效字段由新的枚举类型表示，并且包含对可接受值的更改：
  • metadata.status.format 现在使用 Format 枚举。在转换为此枚举时，值 EXCEL_CSV 已被移除，并添加了 FORMAT_UNSPECIFIED。
  • metadata.status.state 现在使用 State 枚举。在转换为此枚举时，添加了 QUEUED 和 STATE_UNSPECIFIED 值。
  • params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match 和 params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match 现在使用 Match 枚举。
  • params.options.pathQueryOptions.pathFilters[].pathMatchPosition 现在使用 PathMatchPosition 枚举。在转换为此枚举时，添加了值 PATH_MATCH_POSITION_UNSPECIFIED。
  • params.type 现在使用 ReportType 枚举。在转换为此枚举时，已经进行了多项更改，这些更改在上一部分中有关更新查询服务调用的部分中详细列出了。
• 字段 metadata.reportDataStartTimeMs 和 metadata.reportDataEndTimeMs 已替换为 ReportMetadata 对象中的 reportDataStartDate 和 reportDataEndDate 字段。新字段使用 Date 对象，而不是自 Unix Epoch 以来的毫秒数。
• metadata.status.finishTimeMs 已替换为 ReportStatus 对象中的 finishTime 字段。这个新的时间字段以 RFC3339 UTC（即“祖鲁时”）格式（而不是自 Unix Epoch 以来的毫秒数）表示日期时间。
• 移除了 metadata.status.failure 和 params.includeInviteData 字段。
• 移除了 reports.list 响应正文中的 kind 字段。

更新错误处理逻辑

v2 中更新了 API 中的错误消息。这些新的错误消息更加具体，并且在某些情况下，会提供有关 API 请求中导致返回错误的值的信息。如果现有的错误处理逻辑依赖于特定的错误消息文本，请在迁移到 v2 之前泛化错误处理。