请求报告

新版 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 中会返回该时区。