从 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 是已知的 如 queries 和 queries.reports（在 v2 中相同）。
• 在 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 资源中的以下字段最初由常规 list 对象已更改为以下新对象类型的列表：

  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 中由枚举类型表示，并包括以下内容 更改： <ph type="x-smartling-placeholder">
  </ph>
  • 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 对象的 dataRange 字段， QueryMetadata 对象。
• 字段 schedule.startTimeMs 和 schedule.endTimeMs 已替换为字段 startDate 和 endDate（位于 QuerySchedule 对象。新的日期字段使用 Date 对象，而非自 Unix Epoch 以来的毫秒数。
• 字段 metadata.running、 metadata.reportCount, metadata.googleCloudStoragePathForLatestReport, metadata.googleDrivePathForLatestReport 和 已移除 metadata.latestReportRunTimeMs。 有关最近生成的查询报告的信息应 而是使用 queries.reports.list 方法进行检索，且 将“key.reportId desc”的 orderBy 查询参数设置为 保证请求首先列出最新的报告。
• 字段 kind、timezoneCode、 metadata.locale, params.includeInviteData 和 已移除 schedule.nextRunMinuteOfDay。
• queries.create 在创建后不再自动运行查询 移除了 asynchronous 查询参数。致电 queries.create之后的queries.run，即可生成以下内容的报告： 新查询。
• queries.run 方法在以下方面进行了更新：
  • asynchronous 查询参数已替换为 synchronous 查询参数。新的查询参数 以逆逻辑运算，如果未指定，则视为 false。给定 因此，queries.run 默认在 同步，而后者是 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 中的等效字段以新的 枚举类型，并包含对可接受值的更改： <ph type="x-smartling-placeholder">
  </ph>
  • 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已替换为 字段reportDataStartDate和 reportDataEndDate（位于 ReportMetadata 对象。新字段使用 Date 对象，而非自 Unix Epoch 以来的毫秒数。
• metadata.status.finishTimeMs已被替换为 字段中的 finishTime 字段 ReportStatus 对象。这个新的时间字段表示 日期时间（采用 RFC3339 世界协调时间 (UTC)，即“祖鲁时”）的时间戳格式，而不是 自 Unix Epoch 起的毫秒数。
• metadata.status.failure和 已移除 params.includeInviteData 个字段。
• reports.list 响应正文中的 kind 字段包含 已移除。

更新错误处理逻辑

整个 API 中的错误消息在 v2 中已更新。这些新的错误消息 更具体，在某些情况下，还会提供 引发错误的 API 请求。如果现有错误 处理逻辑依赖于特定的错误消息文本，概括您的错误 处理。