零展示和结构报告

除了提取效果统计信息之外,AdWords API 开发者还经常使用报告系统来获取有关帐号的结构信息。

本指南介绍如何解读和管理报告中的零展示统计信息以及如何在构建帐号结构时加以运用。

报告中的零展示统计信息

在您的报告中,您可能会发现有些没有被浏览过的实体会显示零展示统计信息。导致这种情况的原因可能有多种,例如,相应实体不符合展示的条件或者在报告的日期范围内可能已被暂停。

这些零展示对于效果计算没有什么用处,但要下载帐号的完整内容,却需要它们。

零展示报告用于发现帐号中的实体结构或快速同步本地数据库,而无需对 API 进行一系列代价高昂的 get() 调用。通过在结果中包含零展示,您可以在单次调用中发现任何帐号实体的结构。

包含和排除零展示

所有常规效果报告都可能返回零展示数据,因此您应该始终根据自己的使用情形明确包含或排除零展示。这可以避免您的请求有任何含糊之处,并且如果您的请求中存在报告字段和零展示行为的无效组合,可让 API 提供有意义的错误消息。

什么时候应该包含零展示

零展示对于在单次调用中显示帐号的实体结构很有用。另一种方法是发出大量 API 请求,但这可能触发速率限制

例如,如果针对 IdCriteria 查询关键字效果报告且排除零展示,可能仅能提取极少量结果;但是通过包含零展示并添加诸如 CampaignIdAdGroupId 等字段,就可以处理并构建当前已知关键字的结构

什么时候应该排除零展示

零展示对于发现实体结构很有用,但通常应从效果报告中排除。排除零展示可以减少响应规模,或只关注给定日期范围内有意义的效果统计信息。如果在给定报告中有很多已暂停的广告系列,那么这样做特别有用,因为零展示可能会不必要地加大结果集的规模。

包含零展示

要在报告输出中包含零展示,请将 includeZeroImpressions HTTP 标头设置为 true

设置为 true 时,报告不会根据指标值排除任何行,并且会包含展示次数为零的行。

排除零展示

有两种方法可以明确地从报告中排除零展示:

  • includeZeroImpressions HTTP 标头设置为 false
  • 使用谓词。

将 includeZeroImpressions HTTP 头设置为 false

排除零展示的最简单方法是将 includeZeroImpressions HTTP 标头设置为 false

当设置为 false 时,报告将仅返回符合以下条件的行:请求的 Metric 字段中至少有一个具有非零值。

使用谓词排除零展示

通过为 Impressions 字段添加一个运算符为 GREATER_THAN 且值为 0 的谓词,可以排除零展示。

此谓词的 XML 结构如下所示

<predicates>
  <field>Impressions</field>
  <operator>GREATER_THAN</operator>
  <values>0</values>
</predicates>

AWQL 语句如下所示

WHERE Impressions > 0

隐式排除零展示

如果报告请求包含任何不支持零展示的字段,零展示行会被隐式排除。可以在报告类型页的支持零展示属性中查看每个字段的零展示行为。

但是,最好不要依赖隐式排除,原因是在请求中添加或移除一个字段可能会改变报告的行为。

结构报告

使用 API 服务全面收集您帐号的数据可能会很慢,尤其是在帐号增长时。

AdWords 报告可让您更轻松地获取帐号及其相关实体的基本结构信息:您可以使用报告快速返回数据(包括对象 ID、名称和值),以重现帐号的基本框架。您可以在此处找出希望详细了解的元素,并使用其对象 ID 从 API 提取详细信息。

报告类型文档说明了可以为每个帐号对象提取哪些列条目。也可以使用 ReportDefinitionService 的 getReportFields() 方法,采用编程方式获取这些列标题。通过仔细选择报告列,您可以获取足够的信息来构建帐号结构。

广告系列示例

此示例演示了如何收集帐号中每个广告系列的某些相关数据。使用 AWQL 请求收集数据,然后将返回的数据插入本地数据库。然后,您可以发出本地 SELECT 请求来构建您所关注的结构表格。

以下步骤和代码段说明了如何构建广告系列表格:

  1. 从报告中查询广告系列数据,方法是通过构建 AWQL 请求字符串来指定广告系列效果报告中所有必需的列标题。您还必须声明报告类型和查询的日期范围。然后使用查询创建报告,将 CSV 指定为下载格式。

    SELECT CampaignStatus, CampaignId, CampaignName, ExternalCustomerId,
        CustomerDescriptiveName, Amount, BiddingStrategyId, Impressions
    FROM CAMPAIGN_PERFORMANCE_REPORT
    DURING YESTERDAY
    

  2. 创建本地广告系列表格。这一语句用于创建表格,同时还会在 SQLite 表格中清楚地说明列标题及其类型。

    CREATE TABLE campaigns (Status STRING, id LONG, name STRING, extCID LONG,
        custName STRING, amount FLOAT, biddingStrategyId LONG, impressions INTEGER)
    

  3. 填写广告系列表格。下面的 SQL 语句将条目插入到 campaigns 表中。使用在报告下载中收到的值为每个“?”设置参数值。

    INSERT INTO campaigns (Status, id, name, extCID, custName, amount,
        biddingStrategyId, impressions) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
    

报告格式

报告可以是 CSV 或 XML 等多种格式,不过使用 CSV,您只需通过现有的库,即可为响应流提供输入,从而对每个条目进行过滤,得到您所选的对象格式。CSV 输出内容也更简洁,因此处理速度通常会快一些。

默认情况下,CSV 报告的第一行为报告标题,第二行为列标题,后跟结果,最后为汇总 Total 行。下面的广告系列效果报告响应示例展示了默认格式:

"CAMPAIGN_PERFORMANCE_REPORT (Apr 1, 2015-Apr 6, 2015)"
Campaign state,Campaign ID,Campaign,Customer ID,Account,Cost,Bid Strategy Name,Impressions
paused,143072203,Search + DSAs,1234567890,My AdWords Account,0, --,0
paused,168682400,Interplanetary Cruise 1396462861759,1234567890,My AdWords Account,0, --,0
paused,168682099,Interplanetary Cruise 1396462699054,1234567890,My AdWords Account,0, --,0
enabled,238539688,Campaign 1234,1234567890,My AdWords Account,5970000, --,902
Total, --, --, --, --,5970000, --,902

采用此默认格式的报告标题行后跟请求的列名称(列在第二行中)。除非您请求重复列(在这种情况下省略第二个实例),否则返回列的顺序与请求中指定的顺序相同。汇总行对报告进行总结。

在解析数据并将数据插入数据库时,请务必忽略前两行以及末尾的 Total 行,然后插入剩余的每一行。或者,您可以对请求设置可选标头,以便从响应中省略报告标题、列标题和汇总,只留下数据本身。

您可以为广告组、广告和条件重复这些任务,然后使用 SQL 查询刚刚填充的本地数据库。您可以修改此示例,以根据需要对收集的数据加以利用,例如:

SELECT * FROM campaigns
LEFT OUTER JOIN adGroups ON campaigns.id=adGroups.campaignId
LEFT OUTER JOIN ads ON ads.adAdGroupId=adGroups.adGroupId

SELECT * FROM criteria
JOIN keywords
WHERE criteria.critType='Keyword' AND keywords.keywordId=criteria.critId

提示和技巧

使用此方法提取帐号数据时,请记住以下提示:

  • 在请求特定报告时,添加一些会阻止系统返回包含零展示的行的列,会导致无法获得任何结果。广告效果报告中的 KeywordId 字段就属于这样一种情况,该字段的备注列及其支持零展示列的 False 值说明了这一点。其他列可能是互斥的,例如 ConversionTypeNameClicks。下载结构数据时应避免使用这些列标题,请改用行为列中作为属性列出的列标题。

  • 您应避免请求重复的列,因为它们会从响应中移除,并且可能会扰乱对数据的解析。有关如何设置列格式的规范,请参阅报告类型页中的备注列。

  • 如果选择不使用可选标头来排除汇总 Total 行,而是通过提供字词 Total 来表示解析的结束,那么在选择您的 AWQL 查询中的第一列时务必小心,字词 Total 不能作为该列的值之一,否则您将提前终止解析。例如,您可以放心地将 ID 用作第一列,其类型是长整型。在该示例中,我们所选择的 Status 列包含具有有限一组值的字符串。

  • 务必确保每列的类型正确无误。如果您收到意外的内容,然后针对其调用特定于类型的字符串解析器,则在通过字符串将这些值解析为正确的值时会导致异常。

发送以下问题的反馈:

此网页
AdWords API
AdWords API
需要帮助?请访问我们的支持页面