请求报告

新版 Search Ads 360 Reporting API 现已发布。这个新 API 让您可以更灵活地生成自定义报告,并将数据整合到您的报告应用和流程中。您可以详细了解如何迁移到和使用新版 Search Ads 360 Reporting API

按照我的第一个应用中的说明设置客户端应用后,您可以使用 Search Ads 360 API 请求和下载报告。您可以发出以下任一类型的请求:

同步

只需一个请求,并以 JSON 格式的响应返回报告。同步请求:

如果您要请求大型广告客户报表或引擎帐号报表,我们建议您使用异步方法。

异步

需要您发送初始请求,用于指定想要在报告中包含的数据。然后,您发送额外的请求来轮询 Search Ads 360。在 Search Ads 360 生成报告后,您可以发送将报告下载为一个或多个文件的请求。异步请求:

  • 可以返回任何报告类型
  • 将非常大的报告拆分为多个文件
  • 将报告的格式设置为 CSV 或 TSV

数据模型:行和列

Search Ads 360 会将报告中的数据整理成行和列。 您请求的报告类型决定了返回的。 例如,如果您请求关键字报告,则每一行都包含有关一个关键字的数据。如需查看所有报告类型的列表,请参阅报告类型参考文档。 您可以对报告请求中的每一列进行命名,从而指定要在报告中包含的列。有关每种报告类型可以返回的列的列表,请参阅报告类型参考。

列行为

列的行为取决于列包含的数据类型(报告类型参考文档中显示了每列的行为):

  • 属性列。属性列包含用于配置或标识广告系列中的实体的数据,例如广告系列名称或关键字出价。无论请求中指定的日期或日期范围如何,Search Ads 360 API 始终会返回属性列的当前值。例如,如果您昨天将某个关键字的出价从 2.00 更改为 1.50,然后请求生成上个月数据的报告,则报告将为该关键字出价返回 1.50 的值。

  • 指标列。指标列包含有关广告系列效果的数据(例如广告的点击次数、Floodlight 代码记录的访问次数或收入)。除非您指定时间范围为一天,否则 API 会返回指标列的汇总值。例如,如果您请求获取上个月数据的报告,API 会返回上个月的总点击次数。

  • 对列进行细分。细分列会将数据拆分为单独的行。 例如,date 是您可以为多种类型的报告指定的细分列。如果您在日期范围为 2013-01-01 至 2013-01-07 的关键字报告中指定 date 列,则 API 将为每个关键字返回 7 行,每行对应一天,并显示当天的指标。请参阅细分报告

币种

您的报告请求必须指定货币数据的货币(dailyBudget 等属性和 cost 等指标)。您可以指定以下项之一:

  • 代理机构使用的币种(如果报表范围限定为某个代理机构、广告客户或引擎帐号)。
  • 广告客户的币种(如果报表的范围限定为广告客户或引擎帐号)。
  • 引擎帐号的币种(如果报表的范围限定为引擎帐号)。
  • USD

使用 Reports.request.statisticsCurrency 请求属性可指定货币。

报告本身会在 Reports.statisticsCurrencyCode 属性中指明币种。

时区

Search Ads 360 指标的存储日期不包含时区。这些日期对应于引擎指标(如点击次数、展示次数和访问次数)的引擎帐号时区,以及转化指标(如非购买型操作数、交易次数和收入)的 Campaign Manager 广告网络时区。当报告中的每个指标都来自同一时区时,请求中将返回该时区。否则,系统不会返回任何时区。 您的请求可以将 Reports.request.verifySingleTimeZone: true 设置为失败报告,这些报告可显示多个时区的指标。

如果报告中的所有指标均来自一个时区,Reports.statisticsTimeZoneReports 中会返回该时区。