本指南涵盖实时出价问题排查资源,让您能够以编程方式访问实时出价广告系列指标,这些指标也可通过 Authorized Buyers 界面中的实时出价明细工具查看。包括 bidders.filterSets
、bidders.accounts.filterSets
及其下层的所有资源。
借助实时出价问题排查资源中的指标,您可以深入了解错失的展示机会,从而优化实时出价广告系列。
对 API 结构和样式进行的调整
实时出价问题排查资源进行了一些更改,以明确指明所有权和访问权限,更精细地控制 API 返回的数据,并更好地契合 Google API 设计做法。
出价方级和账号级资源
资源在 bidders
和 bidders.accounts
下进行结构化处理。通过这两个属性,您可以指定 API 调用的目标对象是出价方(也称为父帐号)及所有关联的子帐号,还是各个 Authorized Buyers 帐号。在使用实时出价问题排查时,bidders.filterSets
下结构化的资源将返回指定出价方及所有关联子帐号的汇总指标。相比之下,bidders.accounts.filterSets
下的选项将仅返回指定帐号的指标,无论该帐号是出价方还是子帐号。
注意:将出价委托给其他买方的帐号不是出价工具帐号,因此无法访问出价工具级资源。此外,非出价方帐号无法访问帐号级 impressionMetrics
、filteredBidResponses
、bidResponseErrors
和 bidResponsesWithoutBids
资源。
将资源名称作为唯一标识符引入
资源名称用作唯一标识符,而不是整数或字符串 ID。现在,创建给定资源类型的新实例时,您必须使用资源的 URI 路径后跟首选资源 ID 来指定相对资源名称。以下是与实时出价问题排查资源相关的名称示例:
资源 | 名称示例 |
---|---|
bidders.filterSets | bidders/12345678/filterSets/fset_1 |
bidders.accounts.filterSets | bidders/12345678/accounts/87654321/filterSets/fset_2 |
注意:在名称中为 bidders
指定的资源 ID 必须是出价方的 Authorized Buyers 帐号 ID。对于 accounts
,资源 ID 必须是出价方的帐号 ID 或由其管理的子帐号。如果您不知道哪些 Authorized Buyers 帐号与您的 Google 帐号相关联,您可以使用 accounts.list 方法查找这些帐号。
过滤条件集
过滤条件集表示可用的过滤选项,可在出价方或帐号一级创建。该属性用于过滤实时出价问题排查资源的列表结果,这些资源会检索您的实时出价广告系列的指标。
检索指标时应用的过滤条件是指定过滤条件集中每个过滤条件的交集。列表过滤条件(例如 platforms
)被解释为列表中每个项的并集。
出价工具集和帐号级过滤条件集是不同的,只能从创建时所在的级别进行访问(无论用于创建它们的帐号是什么)。出价方和子帐号共享过滤条件集在帐号一级创建,而只有出价方可以访问出价工具一级的资源。下表总结了出价方和子帐号如何在任一层级访问资源:
bidders.filterSets | bidders.accounts.filterSets | |
---|---|---|
出价方账号 | 仅影响出价方级过滤条件集的 API 调用。 | 仅影响帐号级过滤条件集的 API 调用。 |
儿童账户 | 此 API 调用将返回错误响应。 | 仅影响帐号级过滤条件集的 API 调用。 |
创建过滤条件集
创建过滤条件集时,您必须以 relativeDateRange
、absoluteDateRange
或 realtimeTimeRange
的形式指定时间范围。检索指标时,默认行为是提供整个时间范围内的所有数据。如果您希望接收该时间范围内的时序细分,可以指定 timeSeriesGranularity
以指示 HOURLY
或 DAILY
间隔。
如果您只需要短时间内设置的过滤条件,可以将 isTransient
查询参数设置为 true
。这表明该过滤器集是暂时性的,也就是说它不会无限期地存在。暂时性过滤条件集在创建后至少还会持续一小时内可用,但最终会被删除。默认情况下,过滤器集不是暂时性的。
出价方级示例
若要创建新的出价方级过滤条件集,请向 bidders.filterSets
资源 URI 发送 POST
请求,格式如下:
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets
警告:出价方级过滤条件集无法按广告素材 ID 或交易 ID 进行过滤。如果您在创建出价方级过滤条件集时指定这些过滤条件,则会收到错误响应。
请求下例中的 POST
请求会创建一个新的非暂时性出价方级过滤条件集:
POST https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets Authorization: Bearer access token here Content-Type: application/json { "name": "bidders/12345678/filterSets/bidder-fs", "format": "DISPLAY", "environment": "APP", "platforms": ["TABLET", "MOBILE"], "absoluteDateRange": { "startDate": { "month": 11, "day": 26, "year": 2017 }, "endDate": { "month": 12, "day": 3, "year": 2017 } }, "timeSeriesGranularity": "DAILY" }响应
如果请求成功,服务器会返回 200 OK 状态代码。响应正文将包含已创建的过滤条件集资源,该资源与请求中提交的过滤条件集完全相同。
账号级示例
要创建新的帐号级过滤条件集,请向 bidders.accounts.filterSets
资源 URI 发送 POST
请求,格式如下:
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets
注意:为 accounts
指定的资源 ID 可以是该 URI 中指定的出价方帐号(包括该出价方帐号本身)可访问的任何 Authorized Buyers 帐号的帐号 ID。
下例中的 POST
请求会创建一个新的非暂时性帐号级过滤条件集:
POST https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets Authorization: Bearer access token here Content-Type: application/json { "name": "bidders/12345678/accounts/87654321/filterSets/account-fs", "format": "VIDEO", "environment": "WEB", "platforms": ["DESKTOP"], "absoluteDateRange": { "startDate": { "month": 11, "day": 26, "year": 2017 }, "endDate": { "month": 12, "day": 3, "year": 2017 } }, "timeSeriesGranularity": "DAILY" }响应
如果请求成功,服务器会返回 200 OK 状态代码。响应正文将包含已创建的过滤条件集资源,该资源与请求中提交的过滤条件集相同。
设置过滤条件
get 方法只能获取在创建其所在层级的过滤器集。例如,出价工具帐号应使用 bidders.accounts.filterSets.get
(而不是 bidders.filterSets.get
方法)获取在帐号一级创建的过滤条件集。
出价方级
要获取出价工具级过滤条件,可以向 bidders.filterSets
资源 URI 发送 HTTP GET 请求,格式如下:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}请求
示例如下:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fs响应
如果请求成功,服务器将返回 200 OK
HTTP 状态代码以及检索到的过滤器集:
{ "name": "bidders/12345678/filterSets/bidder-fs", "format": "DISPLAY", "environment": "APP", "platforms": ["TABLET", "MOBILE"], "absoluteDateRange": { "startDate": { "month": 11, "day": 26, "year": 2017 }, "endDate": { "month": 12, "day": 3, "year": 2017 } }, "timeSeriesGranularity": "DAILY" }
账号级
要获取帐号级过滤条件集,可以向 bidders.accounts.filterSets
资源 URI 发送 HTTP GET
请求,格式如下:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}请求
示例如下:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fs响应
如果请求成功,服务器将返回 200 OK
HTTP 状态代码以及检索到的过滤器集:
{ "name": "bidders/12345678/accounts/87654321/filterSets/account-fs", "format": "VIDEO", "environment": "WEB", "platforms": ["DESKTOP"], "absoluteDateRange": { "startDate": { "month": 11, "day": 26, "year": 2017 }, "endDate": { "month": 12, "day": 3, "year": 2017 } }, "timeSeriesGranularity": "DAILY" }
列出过滤条件集
list 方法将仅返回可从被调用的级别访问的过滤条件集。例如,调用 bidders.filterSets.list
时,出价方帐号不会看到通过 bidders.accounts.filterSets.create
为自己创建的过滤条件集。
出价方级
您可以向 bidders.filtersets
资源 URI 发送 HTTP GET
请求,格式如下,以检索给定出价方的所有出价方级过滤条件集:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets请求
以下示例列出了帐号 ID 为 12345678 的出价方的所有出价方级过滤条件集:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets响应
{ "filterSets": [{ "filterSetId": "99994", "name": "bidders/12345678/filterSets/test-b-1", "relativeDateRange": { "durationDays": 30 } }, { "realtimeTimeRange": { "startTimeStamp": "2017-11-15T12:30:30.072831583Z" }, "filterSetId": "99995", "name": "bidders/12345678/filterSets/test-b-2", "timeSeriesGranularity": "HOURLY" }, { "absoluteDateRange": { "endDate": { "day": 12, "month": 3, "year": 2017 }, "startDate": { "day": 26, "month": 11, "year": 2017 } }, "filterSetId": "99996", "name": "bidders/12345678/filterSets/bidder-fs", "timeSeriesGranularity": "DAILY", "platforms": ["TABLET", "MOBILE"], "environment": "APP", "format": "DISPLAY" } ] }
账号级
要获取给定帐号的所有帐号级过滤条件集,可以向 bidders.accounts.filtersets
资源 URI 发送 HTTP GET
请求,格式如下:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets请求
以下示例列出了帐号 ID 为 87654321 的子帐号的所有帐号级过滤条件集:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets响应
{ "filterSets": [{ "realtimeTimeRange": { "startTimeStamp": "2017-11-19T04:24:43.252893487Z" }, "filterSetId": "99997", "name": "bidders/12345678/accounts/87654321/filterSets/test-a-1", "timeSeriesGranularity": "DAILY" }, { "absoluteDateRange": { "endDate": { "day": 3, "month": 12, "year": 2017 }, "startDate": { "day": 26, "month": 11, "year": 2017 } }, "filterSetId": "99998", "name": "bidders/12345678/accounts/87654321/filterSets/account-fs", "timeSeriesGranularity": "DAILY", "platforms": ["DESKTOP"], "environment": "WEB", "format": "VIDEO" } ] }
删除过滤条件集
您可以使用 delete
方法移除不再需要的任何非瞬态滤波器集。它只能移除可从其被调用的级别访问的过滤条件集;例如,出价工具帐号无法删除通过 bidders.accounts.filterSets.create
使用 bidders.filterSets.delete
创建的过滤条件集。
出价方级
若要删除为给定帐号设置的出价工具级过滤条件,您可以向 bidders.filtersets
资源 URI 发送 HTTP DELETE
请求,格式如下:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}请求
以下是删除出价方级过滤条件集的示例:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/test-b-2响应
如果请求成功,请求正文将为空。指定的过滤条件集将无法再访问。
账号级
要删除为给定帐号设置的帐号级过滤条件,您可以向 bidders.accounts.filtersets
资源 URI 发送 HTTP DELETE
请求,格式如下:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}请求
以下是删除帐号级过滤条件集的示例:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/test-a-1响应
如果请求成功,请求正文将为空。指定的过滤条件集将无法再访问。
检索实时出价问题排查指标
所有用于接收指标的实时出价问题排查资源都以类似方式运作:它们使用单一方法列出通过 filterSetName
路径参数指定的过滤条件集的指标。指定的过滤条件集将决定在查询指标时将应用哪些过滤条件和设置。从出价工具级别调用这些资源将返回出价工具帐号和所有关联子帐号的汇总指标,而从帐号级别调用将仅返回具体帐号的指标。
出价指标
bidMetrics
资源用于检索以出价数衡量的指标。例如,您可以使用此参数来确定指定时间范围内的出价总数,以及其中有多少出价未从竞价中滤除或赢得展示等。与用于收集指标的所有其他实时出价问题排查资源一样,它只有 list
方法。
列出出价方级出价指标
您可以向 bidders.filtersets.bidMetrics
资源 URI 发送 HTTP GET
请求(格式如下),从而列出指定过滤条件集的出价指标:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}/bidMetrics请求
以下示例列出了出价工具级出价指标:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fs/bidMetrics响应
如果请求成功,服务器将会返回 200 OK
状态代码以及一个包含指定维度和粒度指标行的正文。
{ "bidMetricsRows": [{ "bids": { "value": "6160" }, "bidsInAuction": { "value": "5698" }, "billedImpressions": { "value": "1196" }, "impressionsWon": { "value": "2920" }, "measurableImpressions": { "value": "1160" }, "rowDimensions": { "timeInterval": { "endTime": "2017-11-29T08:00:00Z", "startTime": "2017-11-28T08:00:00Z" } }, "viewableImpressions": { "value": "683" } }, { "bids": { "value": "104288" }, "bidsInAuction": { "value": "94016" }, "billedImpressions": { "value": "99" }, "impressionsWon": { "value": "125" }, "measurableImpressions": { "value": "94" }, "rowDimensions": { "timeInterval": { "endTime": "2017-11-30T08:00:00Z", "startTime": "2017-11-29T08:00:00Z" } }, "viewableImpressions": { "value": "87" } }, { "bids": { "value": "3999" }, "bidsInAuction": { "value": "3631" }, "billedImpressions": { "value": "618" }, "impressionsWon": { "value": "1819" }, "measurableImpressions": { "value": "604" }, "rowDimensions": { "timeInterval": { "endTime": "2017-12-01T08:00:00Z", "startTime": "2017-11-30T08:00:00Z" } }, "viewableImpressions": { "value": "369" } }, { "bids": { "value": "15" }, "bidsInAuction": { "value": "3" }, "billedImpressions": {}, "impressionsWon": { "value": "3" }, "measurableImpressions": {}, "rowDimensions": { "timeInterval": { "endTime": "2017-12-02T08:00:00Z", "startTime": "2017-12-01T08:00:00Z" } }, "viewableImpressions": {} } ] }
注意:对于给定指标,任何设置为 0 的字段都不会显示在响应中。
上面的空 billedImpressions
和 measurableImpressions
指标表示这些指标的值和方差都设置为 0。
警告:对于响应中的任何数据细分,响应将不包含不包含任何非零指标的行。例如,如果指定了 timeSeriesGranularity
,响应将不包含过滤条件集的指定时间范围内(所有指标都为零)内任何 timeInterval
的行。
列出账号级出价指标
您可以向 bidders.accounts.filtersets.bidMetrics
资源 URI 发送 HTTP GET
请求(格式如下),从而列出指定过滤条件集的帐号级出价指标:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}/bidMetrics请求
下面是列出帐号级出价指标的示例:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fs/bidMetrics响应
如果请求成功,服务器将会返回 200 OK
状态代码以及一个包含指定维度和粒度指标行的正文。
{ "bidMetricsRows": [{ "bids": { "value": "1748" }, "bidsInAuction": { "value": "1421" }, "billedImpressions": { "value": "301" }, "impressionsWon": { "value": "915" }, "measurableImpressions": { "value": "298" }, "rowDimensions": { "timeInterval": { "endTime": "2017-12-01T08:00:00Z", "startTime": "2017-11-30T08:00:00Z" } }, "viewableImpressions": { "value": "172" } }, { "bids": { "value": "6" }, "bidsInAuction": { "value": "2" }, "billedImpressions": {}, "impressionsWon": { "value": "1" }, "measurableImpressions": {}, "rowDimensions": { "timeInterval": { "endTime": "2017-12-02T08:00:00Z", "startTime": "2017-12-01T08:00:00Z" } }, "viewableImpressions": {} } ] }
注意:对于给定指标,设置为 0 的所有字段都不会显示在响应中。上面的空 billedImpressions
和 measurableImpressions
指标表示这些指标的值和方差都设置为 0。
警告:对于响应中的任何细分数据,响应将不包含至少一个非零指标的行。例如,如果指定了 timeSeriesGranularity
,响应将不包含过滤条件集的指定时间范围内(所有指标都为零)内任何 timeInterval
的行。