报告的相关基础知识

效果数据报告是大多数 AdWords API 应用不可或缺的一部分。借助于 API 灵活的报告选项,您既可以生成整个广告系列的效果数据报告,也可以制作更为具体的专项报告,例如有关触发广告的搜索查询的报告。

本指南将介绍创建报告请求和向 AdWords 服务器提交报告请求的必要步骤,然后将介绍一些高级报告概念,如数据细分、数据格式和归因。

有关 AdWords API 中所有可用报告类型的完整列表,请参阅报告类型参考页。

概览

从 API 生成报告分为两个主要步骤:

  1. 创建报告定义。报告定义是指用于定义报告参数的 XML 或 AWQL 片段,这些参数包括报告名称、纳入报告的信息类型、下载格式以及一些其他详细信息。
  2. 将报告定义包含在 HTTP POST 请求中,然后将其提交至 AdWords 服务器。

下面我们详细介绍这两个步骤。

创建报告定义

报告定义是请求的正文,用于指定报告中应包含的元素。

您可以使用 XML 或 AWQL( AdWords 查询语言)创建报告定义。

以下部分介绍了基于 XML 的报告定义。如果您想使用 AWQL 而不是 XML,请参阅 AWQL 指南中的报告部分

以下是 XML 报告定义的一个示例。示例下方的表格定义了报告定义中的每个元素。

XML

<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201609">
  <selector>
<fields>CampaignId</fields>
<fields>AdGroupId</fields>
<fields>Impressions</fields>
<fields>Clicks</fields>
<fields>Cost</fields>
<predicates>
  <field>AdGroupStatus</field>
  <operator>IN</operator>
  <values>ENABLED</values>
  <values>PAUSED</values>
</predicates>
  </selector>
  <reportName>Custom Adgroup Performance Report</reportName>
  <reportType>ADGROUP_PERFORMANCE_REPORT</reportType>
  <dateRangeType>LAST_7_DAYS</dateRangeType>
  <downloadFormat>CSV</downloadFormat>
</reportDefinition>

AWQL

SELECT CampaignId, AdGroupId, Impressions, Clicks, Cost
FROM ADGROUP_PERFORMANCE_REPORT
WHERE AdGroupStatus IN [ENABLED, PAUSED]
DURING LAST_7_DAYS
报告定义中的元素 说明
<reportDefinition> 这是报告定义的标头。请使用请求中显示的同一个网址,确保列出 API 的正确版本。
<selector> 选择器部分包含您想选择添加到报告中的数据元素的 fields 列表。查看报告类型页面,详细了解此处可用的值。请注意,可用的字段列表取决于所指定的 reportType

您还可以使用 ReportDefinitionService.getReportFields() 方法以编程方式获取可用字段列表。

<predicates> 谓词相当于 AdWords 界面中的过滤条件。谓词由报告字段、运算符和值组成。谓词会被视为并存关系 (AND) 条件。
<reportType> 指示您所请求的报告的类型。要了解更多信息并查看完整的报告类型列表,请参阅报告类型页面。
<dateRangeType> 报告应涵盖的日期范围。有关详情,请查看下文中的日期范围部分。
<downloadFormat> 您要以哪种格式下载报告。有关详情,请查看下文中的下载格式部分。

XML 架构定义

以下网址中发布了用于定义 reportDefinition 结构的 XML 架构定义 (XSD):

https://adwords.google.com/api/adwords/reportdownload/v201609/reportDefinition.xsd

application/x-www-form-urlencodedmultipart/form-data 这两种内容类型均受支持;对于前一种内容类型,您需要对所提交的 XML 进行网址编码。

日期范围

要指定报告的日期范围,请使用 ReportDefinition.DateRangeType,后者来自报告定义 XSD

有效的 DateRange 类型 所生成报告的日期范围
TODAY 仅限今天。
YESTERDAY 仅限昨天。
LAST_7_DAYS 过去 7 天(不包含今天)。
LAST_WEEK 从上周一开始为期七天的时间段。
LAST_BUSINESS_WEEK 上个工作周周一至周五为期五天的时间段。
THIS_MONTH 当月所有日期。
LAST_MONTH 上个月所有日期。
ALL_TIME 整个有效时间范围。
CUSTOM_DATE 自定义日期范围。有关详情,请查看下文中的自定义日期范围部分。
LAST_14_DAYS 过去 14 天(不包含今天)。
LAST_30_DAYS 过去 30 天(不包含今天)。
THIS_WEEK_SUN_TODAY 上周日到当天的时间段。
THIS_WEEK_MON_TODAY 上周一到当天的时间段。
LAST_WEEK_SUN_SAT 从上周日开始为期七天的时间段。

对于每个 ReportDefinition.DateRangeTypeCUSTOM_DATE 除外),只有 dateRangeType 为必需项。

<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201609">
    ...
  <dateRangeType>LAST_7_DAYS</dateRangeType>
</reportDefinition>

自定义日期范围

如果您想使用自定义日期范围,那么您必须:

  1. dateRangeType 指定 CUSTOM_DATE
  2. selector 中,添加一个 dateRange。该字段应包含 min 日期和 max 日期,日期格式为 YYYYMMDD

XML

<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201609">
  <selector>
...
<dateRange>
  <min>20150201</min>
  <max>20150301</max>
</dateRange>
  </selector>
  <dateRangeType>CUSTOM_DATE</dateRangeType>
</reportDefinition>

AWQL

...
DURING 20150201,20150301

数据新鲜度

报告中的一些统计数据可能会不断地进行计算,而其他数据则可能每天计算一次。这是 AdWords 数据新鲜度工作原理的一个方面。要有效地使用报告功能,请参阅数据新鲜度文档。

准备请求

报告定义创建成功后,您就可以开始准备 HTTP POST 请求了。

您可以向 AdWords 服务器直接发送普通 HTTP 同步请求。这种方法开销少,因此更适合数据量很大的报告,特别是在使用多个线程(我们建议从 10 个开始)进行实现的情况下。HTTP 请求是同步请求,因为在报告数据可供下载之前,系统都会实际阻止调用。

在超出服务器所允许打开的连接数量之前,您可能会先超出每秒查询数 (QPS) 限制 (RateExceededError)。报告请求次数不会计入每日操作次数限额,但您不能超出报告的每日下载次数限制

对于 XML 报告定义,POST 请求正文必须包含一个名为“__rdxml”的参数,该参数的值是 XML 报告定义。

请求标头

在下载报告时,请使用正常的 HTTP 标头值:

HTTP 标头 说明
Authorization: Bearer OAUTH2_ACCESS_TOKEN 用于下载报告的授权。请使用 SOAP 请求标头所用的同一个 accessToken
developerToken: DEVELOPER_TOKEN 您的开发者令牌,包含一个唯一字符串,例如“1a2B3c4D5e_-6v7w8x9y0z”
clientCustomerId: CLIENT_CUSTOMER_ID 客户帐号的客户 ID。

您可以通过指定以下可选 HTTP 标头来控制报告是否包含标题行或汇总行:

可选 HTTP 标头 说明
skipReportHeader: true|false 如果选择 true,则报告输出结果不包含显示报告名称和日期范围的标题行。如果选择 false 或不指定,则报告输出结果将包含标题行。
skipColumnHeader: true|false 如果选择 true,则报告输出结果将不包含显示字段名称的标题行。如果选择 false 或不指定,则报告输出结果将包含字段名称。
skipReportSummary: true|false 如果选择 true,则报告输出结果将不包含显示报告总计的汇总行。如果选择 false 或不指定,则报告输出结果将包含汇总行。
useRawEnumValues: true|false 如果您希望返回的格式为实际枚举值(如“IMAGE_AD”而不是“图片广告”),请设置为 true。如果希望返回的格式为显示值,请设置为 false 或忽略此标头。
includeZeroImpressions: true|false 如果设为 true,则报告输出结果将包含所有指定指标字段均为 0 的行,但前提是所请求的字段和谓词都支持零展示。如果设为 false,则报告输出结果将不包含此类行。因此,即使将此标头设为 false,并且某个行的 Impressions 为 0,但只要有任何指定指标字段的值不为 0,那么该行仍然会在报告中出现。如果省略此标头,则报告将使用零展示指南中所述的默认行为。

HTTP 请求网址

此请求包含要提交到 AdWords 服务器的 HTTP POST,服务器网址如下:

https://adwords.google.com/api/adwords/reportdownload/v201609

完整示例

以下完整示例展示了包含在 HTTP POST 请求中的上述报告定义。

XML

POST /api/adwords/reportdownload/v201609 HTTP/1.1
Host: adwords.google.com
User-Agent: curl, gzip
Accept: /
Accept-Encoding: gzip
Authorization: Bearer [Enter OAuth 2.0 access token here]
developerToken: [Enter developerToken here]
clientCustomerId: [Enter clientCustomerID here]
Content-Length: 784
Expect: 100-continue
Content-Type: multipart/form-data; boundary=------------------------12d01fae60c7b559

Parameters:
__rdxml: &lt;?xml version="1.0" encoding="UTF-8"?&gt;
<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201609">
  <selector>
    <fields>CampaignId</fields>
    <fields>AdGroupId</fields>
    <fields>Impressions</fields>
    <fields>Clicks</fields>
    <fields>Cost</fields>
    <predicates>
      <field>AdGroupStatus</field>
      <operator>IN</operator>
      <values>ENABLED</values>
      <values>PAUSED</values>
    </predicates>
  </selector>
  <reportName>Custom Adgroup Performance Report</reportName>
  <reportType>ADGROUP_PERFORMANCE_REPORT</reportType>
  <dateRangeType>LAST_7_DAYS</dateRangeType>
  <downloadFormat>CSV</downloadFormat>
</reportDefinition>

AWQL

POST /api/adwords/reportdownload/v201609 HTTP/1.1
Host: adwords.google.com
User-Agent: curl, gzip
Accept: */*
Accept-Encoding: gzip
Authorization: Bearer [Enter OAuth 2.0 access token here]
developerToken: [Enter developerToken here]
clientCustomerId: [Enter clientCustomerID here]
Content-Length: 182
Expect: 100-continue
Content-Type: multipart/form-data; boundary=------------------------12d01fae60c7b559
 
Parameters:
__fmt: CSV
__rdquery: SELECT CampaignId, AdGroupId, Impressions, Clicks, Cost \
FROM ADGROUP_PERFORMANCE_REPORT \
WHERE AdGroupStatus IN [ENABLED, PAUSED] DURING LAST_7_DAYS

响应代码

如果报告请求成功发出,那么服务器将返回响应代码 200

响应代码 400 代表 API 错误,请检查报告定义中的 XML 是否有问题。

响应代码 500 通常代表服务器发生临时问题。如果出现此错误代码,请在稍后重新发送请求。

多个帐号的报告

一个报告请求只能包含来自一个 AdWords 帐号的数据。如果您需要收集多个帐号的报告数据,请针对每个帐号提交单独的报告请求,方法是设置上文所述clientCustomerId 标头。

超时

如果数据集过大,那么报告下载请求可能会超时。虽然没有明确的数据大小限制,但如果报告过大,服务器可能会因各种因素而返回错误。

如果您遇到超时或发生错误的情况,请尝试缩短日期范围,或使用谓词将报告请求拆分为多个较小的请求。例如,不要生成一个涵盖所有广告系列的报告,而是应该提交多个请求,利用每个请求筛选出一部分广告系列 ID。

支持的下载格式

格式 说明
CSVFOREXCEL 适用于 Excel 的格式。这种格式使用 Unicode 编码,带有 BOM(字节顺序标记)前缀,以便向 Excel 表明其为 Unicode 文件。使用 Unicode 编码时,Excel 默认使用制表符作为分隔符。如果使用逗号作为分隔符,那么 Excel 会将每行的所有数据放入单独的一列中(默认情况下)。
CSV CSV(逗号分隔值)输出格式。
TSV TSV(制表符分隔值)输出格式。
XML XML 输出格式。
GZIPPED_CSV Gzip 压缩的 CSV(逗号分隔值)输出格式。
GZIPPED_XML Gzip 压缩的 XML 输出格式。

选择正确的报告

由于 AdWords API 提供了大量的报告选项,因此为特定业务需求确定合适的报告可能会有些复杂。

使用下面的图表确定最合适的报告,然后在报告类型页上查看该报告的详细信息。

细分

要查看更详细的统计信息,您可以用“细分”来划分数据。举例来说,如果您想专门了解 Google 搜索网络上的展示次数,而不想将其与 Google 展示广告网络上的展示次数混为一谈,那么您就可以按投放网络来细分报告。

细分功能在界面中以一个单独的菜单形式提供,而要在 API 中实现此功能,您只需在报告中添加相应的字段即可。例如,如果您向广告组效果报告添加 AdNetworkType1 字段,生成的报告中就会针对每个广告组和投放网络的组合显示一行信息,其中包含根据二者划分的各项统计数值(展示次数、点击次数、转化次数等)。在界面中每次只能显示一个细分,但在 API 中,您可以在同一个报告中组合多个细分。请注意,在报告中每多添加一个细分字段,报告行数都可能成倍增加。

隐式细分

每个报告都会按其唯一键进行细分。例如,关键字效果报告在选择器字段中未添加 IdAdGroupId 的情况下,也会按这两个元素进行隐式细分,因为关键字由 IdAdGroupId 的组合进行标识。

Keyword,MatchType,Impressions
Keyword1,Exact,3
Keyword2,Exact,10
Keyword3,Exact,5
Keyword4,Broad,4

单一归因与多重归因

当展示广告网络上发生一次展示时,您可按单一归因或多重归因记录对展示起到影响作用的条件。

单一归因

在使用单一归因时,系统只为指定的展示记录一个触发条件(如展示位置、年龄、关键字等)。展示可能是由多项条件触发的,但是在单一归因报告中,展示及其所有统计信息仅归因于单个条件。

每次展示仅统计一次(记录在一个条件下),所有条件加起来的总数与多重归因报告中的总数一致。

条件效果报告和关键字效果报告都使用此模型。

示例报告

下面的示例显示了只定位展示广告网络且只使用行业和展示位置作为条件的广告系列的条件效果报告(属于单一归因)。报告将分 5 行显示总计 10 次展示,3 个展示位置各占一行,触发了展示的 2 个行业各占一行,每个行业各有 2 次展示。

Keyword / Placement,Impressions
www.example.com,2
www.example.ca,2
www.example.net,2
Computers & Electronics,2
Sports,2

多重归因

在使用多重归因时,系统会将展示记录到触发展示的每个维度中的最多一个条件。多重归因报告可以被视为条件类型所特有的报告:与单一归因(其中一行可以包含不同的条件类型)不同,每个多重归因报告仅包含一个条件类型的条件。

例如,性别效果报告按性别汇总了所有展示次数,年龄段效果报告按 AgeRange 汇总了展示次数,等等。展示广告网络主题效果展示位置效果报告也遵循此模型。

与单一归因不同的是,多重归因报告不能汇总,否则会导致重复计算展示次数和点击次数。

示例

Topic,Impressions
Computers & Electronics,6
Sports,4

Placement,Impressions
www.example.com,4
www.example.ca,3
www.example.net,3

如果您只使用行业(主题)和展示位置来定位展示广告,则在您生成“展示广告网络主题”报告时,触发展示的每个行业(主题)都会有对应的一行。同样,展示位置效果报告也会分别为每次展示返回一行。这些报告涵盖的展示相同,因为每次展示最多可归因于一个行业和一个展示位置。

KeywordId=3000000

在单一归因报告中,所有在展示广告网络上触发展示的关键字都由一个特殊的关键字(文本为 Content,ID 为 3000000)来表示。

示例
Keyword ID,Impressions
23458623485,2
23655322314,2
23953456345,2
3000000,4

如果您只针对展示广告网络定位关键字和展示位置,在您生成广告效果报告时,系统将就各展示位置为每个广告和触发条件的组合生成一行,并在单独一行中显示广告以及代表触发了相关广告的所有展示广告网络关键字的 ID 3000000(单一归因会选择关键字而非展示位置)。

KeywordId=3000004

条件 ID 3000004 用于已从 AdWords 移除的一项功能。

KeywordId=3000006

条件 ID 3000006 表示统计信息与展示广告系列优化工具相关。

不同字段的格式

报告中返回的所有字段都包含 Type,但返回的实际值并不一定与这些值一致。请务必查看备注列,其中经常会提供关于值的预期格式的额外信息。例如,ConversionRate 的“备注”列会注明:Percentage returned as "x.xx%"

报告中的 Money 字段

Money 类型的字段将以微货币单位返回,但可能使用前缀“自动:”;如果使用自动出价,可能只使用字符串“自动”。例如 $1.23 将返回为 1230000 (1.23 x 1,000,000)。微单位金额一律指帐号的本地货币。

在根据 Money 字段进行过滤时,您必须提供使用微单位的值。例如,WHERE AverageCpc > 1000000 将返回 AverageCpc 大于 $1(一个单位的帐号货币)的行。

报告的质量得分

关键字效果条件效果报告中将质量得分表示为 1(最低)到 10(最高)。

在 v201607 之前,对于没有足够的展示次数或点击次数以确定质量得分的关键字(例如新关键字或长时间未投放的旧关键字),系统会返回质量得分 6。针对已删除关键字和无法确定质量得分的展示广告网络关键字,则返回质量得分 0。从版本 v201607 开始,采用双短横线 (--) 值表示没有为关键字提供质量得分。此外,在 v201605 中添加了名为 HasQualityScore 的新列,方便过滤未提供质量得分的关键字。例如,以下 AWQL 查询选择具有有效质量得分的关键字:

SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, QualityScore FROM
    CRITERIA_PERFORMANCE_REPORT WHERE Status IN [ENABLED, PAUSED] and
    HasQualityScore='TRUE'

双短横线

如果值为双短横线 (--),即表示此单元格没有值。

列表和映射

列表项将使用 JSON 统一格式;例如 PLACEHOLDER_FEED_ITEM_REPORT 值的 Scheduling 将包含一组字符串数组:

["Monday, 6:00PM - 9:00PM","Tuesday, 6:00PM - 9:00PM","Wednesday,6:00PM - 9:00PM",
"Thursday, 6:00PM - 9:00PM","Friday, 6:00PM - 9:00PM"]

同样,对于映射(例如 UrlCustomParameters):

{"param0":"value0","param1":"value1"}

发送以下问题的反馈:

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