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 调用 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
资源中最初由常规嵌套对象表示的以下字段已更改为使用以下对象类型:Query
资源中最初由常规列表对象表示的以下字段已更改为以下新对象类型的列表: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
资源中最初由常规嵌套对象表示的以下字段已更改为使用以下对象类型:Report
资源中最初由常规列表对象表示的以下字段已更改为以下新对象类型的列表: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 之前泛化错误处理。