从 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	已移除
  params.options.pathQueryOptions.channelGrouping	已移除
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	已移除
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	已移除
  schedule	QuerySchedule

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

  v1.1 列表字段	v2 对象类型
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	已移除
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	已移除
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	已移除
  params.options.pathQueryOptions.pathFilters[]	已移除
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	已移除

• 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 纪元以来的毫秒数。这些替换字段已移至 QueryMetadata 对象中分配给 dataRange 字段的 DataRange 对象中。
• schedule.startTimeMs 和 schedule.endTimeMs 字段已替换为 QuerySchedule 对象中的 startDate 和 endDate 字段。新的日期字段使用 Date 对象，而不是自 Unix 纪元以来的毫秒数。
• 已移除 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	已移除
  params.options.pathQueryOptions.channelGrouping	已移除
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	已移除
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	已移除

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

  v1.1 列表字段	v2 对象类型
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	已移除
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	已移除
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	已移除
  params.options.pathQueryOptions.pathFilters[]	已移除
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	已移除

• 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 枚举。在转换为此枚举的过程中，我们进行了多项更改，这些更改已在上一部分中详细列出，该部分介绍了如何更新查询服务调用。
• ReportMetadata 对象中的字段 metadata.reportDataStartTimeMs 和 metadata.reportDataEndTimeMs 已替换为字段 reportDataStartDate 和 reportDataEndDate。新字段使用 Date 对象，而不是自 Unix 纪元以来的毫秒数。
• metadata.status.finishTimeMs 已替换为 ReportStatus 对象中的 finishTime 字段。这个新的时间字段以 RFC3339 世界协调时间 (UTC)（即“祖鲁时”）格式表示日期时间，而不是以自 Unix 纪元以来的毫秒数表示。
• 移除了 metadata.status.failure 和 params.includeInviteData 字段。
• 已移除 reports.list 响应正文中的 kind 字段。

更新了错误处理逻辑

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