在 Search Ads 360 Reporting API 中创建搜索报告

请阅读以下部分，了解如何在 Search Ads 360 Reporting API 中创建搜索报告。

搜索服务

Search Ads 360 Reporting API 提供用于搜索和生成报告的特殊服务。

SearchAds360Service 是一项统一的对象检索和报告服务，提供两种搜索方法：SearchStream 和 Search。搜索内容以查询字符串的形式传递，该字符串采用 Search Ads 360 查询语言编写。您可以定义查询来：

  • 检索对象的特定属性。
  • 根据日期范围检索对象的效果指标。
  • 根据对象的属性执行对象排序。
  • 使用指定要返回的对象的条件过滤结果
  • 限制返回的对象数量。

这两种搜索方法都会返回与查询匹配的所有行。例如，当您检索 campaign.id、campaign.name 和 metrics.clicks 时，API 会返回一个 SearchAds360Row，其中包含设置了 id 和 name 字段的广告系列对象，以及设置了 clicks 字段的 metrics 对象。

搜索方法

SearchStream

发送单个请求，并与 Search Ads 360 Reporting API 建立持久连接，无论报告大小如何。

  • 数据包会立即开始下载，整个结果会缓存到数据缓冲区中。
  • 您的代码可以开始读取缓冲的数据，而无需等待整个流完成。
Search

发送多个分页请求，以下载整个报告。

SearchStream 通常可提供更好的性能，因为它消除了请求单个网页所需的往返网络时间。我们建议您针对所有超过 1 万行的报告使用 SearchStream。对于较小的报告（<10,000 行），这两种方法在性能方面没有显著差异。

您使用的方法不会影响 API 配额和限制：无论结果是分页还是流式传输，单个查询或报告都算作一次操作。

搜索查询示例

此查询示例会按广告系列返回账号在过去 30 天内的效果数据，并按设备进行细分：

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

发出请求

如需发出请求，您需要向 SearchAds360Service.SearchStream 或 SearchAds360Service.Search 接口传递 customer_id 和 query 字符串。

该请求包含一个指向 Search Ads 360 Reporting API 服务器的 HTTP POST，网址如下：

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream
 
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search

下面是一个完整的报告定义示例，用于 searchStream，包含在 HTTP POST 请求中：

POST /VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream HTTP/1.1
Host: searchads360.googleapis.com
User-Agent: curl
Content-Type: application/json
Accept: application/json
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]

Parameters:
{
  "query" : "SELECT campaign.name, campaign.status, segments.device,
                    metrics.impressions, metrics.clicks, metrics.ctr,
                    metrics.average_cpc, metrics.cost_micros
            FROM campaign
            WHERE segments.date DURING LAST_30_DAYS"
}

处理回答

SearchAds360Service 会返回一个 SearchAds360Row 对象的列表。

每个 SearchAds360Row 都表示查询返回的对象。每个对象都包含一组属性，这些属性会根据查询的 SELECT 子句中请求的字段进行填充。响应中对象的属性（未包含在 SELECT 子句中）不会填充。

例如，以下查询仅使用 campaign.id、campaign.name 和 campaign.status 填充每个 SearchAds360Row 对象。其他属性（例如 campaign.engine_id 或 campaign.bidding_strategy_type）会被省略。

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign

参考文档

参考部分包含正确使用每个制品所需的所有信息。每种资源都有一个页面，例如 ad_group 和 campaign。 segments 和 metrics 页面列出了所有可用的细分和指标字段。

有些资源、细分和指标不兼容，无法一起使用，而另一些则完全兼容，可以相互补充。每个资源页面都包含以下信息（如果适用且可用）以及更多信息：

归因资源

对于某些资源，您可以选择在 FROM 子句中同时选择相关资源的字段和相应资源的字段，从而隐式联接相关资源。例如，campaign 资源是 ad_group 资源的属性化资源。这意味着，在 FROM 子句中使用 ad_group 时，您可以在查询中添加 campaign.id 和 campaign.bidding_strategy_type 等字段。

归因资源部分列出了可用的归因资源。 并非所有资源都有归因资源。

“资源字段”列

资源的所有字段都包含在资源字段列中。每个资源字段都链接到有关该字段的更多详细信息，包括其说明、类别、数据类型、类型网址，以及是否可过滤、可选择、可排序和重复设置。

“细分”列

并非所有细分字段都可与指定资源搭配选择。

细分列列出了可在同一 SELECT 子句中与资源字段搭配使用的 segments 字段。每个字段都链接到有关该字段的完整详细信息，包括其说明、类别、数据类型、类型网址，以及可过滤、可选择、可排序和重复设置。如果您在 FROM 子句中使用资源，则可以使用是/否下拉菜单过滤掉不可用的细分。

指标列

并非所有指标字段都可与给定资源搭配选择。

指标列列出了可在同一 SELECT 子句中与资源字段搭配使用的 metrics 字段。每个字段都链接到有关该字段的完整详细信息，包括其说明、类别、数据类型、类型网址，以及可过滤、可选择、可排序和重复设置。如果您在 FROM 子句中使用资源，请使用是/否下拉菜单过滤掉不可用的指标。

细分资源

某些资源具有细分资源字段，当资源位于 FROM 子句中时，您可以选择这些字段。例如，如果您在 FROM 子句中使用 campaign_budget 时选择 campaign 资源字段（例如 campaign.name），系统会自动返回 campaign.resource_name 并按其进行细分，因为 campaign 是 campaign_budget 的细分资源。

细分资源部分列出了可用的细分资源。 并非所有资源都有分段资源。

可选择的

部分 segments 字段与其他资源、细分和指标不兼容。

segments 页面包含一个可选择的可展开部分，其中列出了所有兼容的资源字段、metrics 字段以及可包含在 SELECT 子句中的其他 segments 字段。segments

细分

您可以通过向查询的 SELECT 子句添加 segments.FIELD_NAME 字段来细分搜索结果。

例如，在以下查询中，segments.device 会生成一个报告，其中包含 FROM 子句中指定资源的每个设备的 impressions 对应的行。

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions
FROM campaign

SearchAds360Service.SearchStream 返回的结果类似于以下 JSON 字符串：

{
  "results":[
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"10922"
      },
      "segments":{
        "device":"MOBILE"
      }
    },
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"28297"
      },
      "segments":{
        "device":"DESKTOP"
      }
    },
    ...
  ]
}

如需查看可使用的细分字段的列表，请参阅 segments。

多个细分

您可以在查询的 SELECT 子句中指定多个细分。响应包含一个 SearchAds360Row 对象，对应于 FROM 子句中指定的主要资源的每个实例与每个所选 segment 字段的值的每个组合。

例如，以下查询将针对 campaign、segments.ad_network_type 和 segments.date 的每种组合返回一行。

SELECT
  segments.ad_network_type
  segments.date
FROM campaign

请注意，系统会按主要资源的每个实例对结果进行隐式细分，但不会按各个选定字段的值进行细分。

以下示例查询会按每个广告系列输出一行结果，而不是按 campaign.status 字段的每个不同的值输出一行结果。

SELECT
  campaign.status,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

隐式细分

每个报告最初都按 FROM 子句中指定的资源进行细分。指标按此资源的 resource_name 字段进行细分

此示例查询会自动返回 ad_group.resource_name，并隐式使用它来细分 ad_group 级别的指标。

SELECT metrics.impressions
FROM ad_group

返回的 JSON 字符串如下所示：

{
  "results":[
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/2222222222"
      },
      "metrics":{
        "impressions":"237"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/33333333333"
      },
      "metrics":{
        "impressions":"15"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/44444444444"
      },
      "metrics":{
        "impressions":"0"
      }
    }
  ]
}

核心日期细分

您可以在 WHERE 子句中使用核心日期段来指定日期或时间段。

以下细分字段称为核心日期细分：segments.date、segments.week、segments.month、segments.quarter 和 segments.year。

此查询示例会返回过去 30 天的广告系列 clicks 指标。

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

核心日期细分字段是例外情况，一般情况下，除非您还在 SELECT 子句中添加了细分字段，否则不能在 WHERE 子句中使用细分字段。如需了解详情，请参阅禁止使用的过滤条件。

核心日期细分规则：

  • 您可以在 WHERE 子句中使用核心日期字段，而无需将其纳入 SELECT 子句中。您也可以根据需要同时在两个子句中添加该字段。

    此示例查询会返回指定日期范围内按广告系列名称划分的 clicks 指标。请注意，segments.date 不包含在 SELECT 子句中。

    SELECT
    campaign.name,
    metrics.clicks
FROM campaign
WHERE segments.date > '2022-02-01'
  AND segments.date < '2022-03-01'

  • 如果您在 SELECT 子句中添加了核心日期字段，则必须在 WHERE 子句中指定有限的日期或日期范围。SELECT 和 WHERE 子句中指定的字段不必匹配。

    此示例查询会返回日期范围内所有天数按月细分的按广告系列名称统计的 clicks 指标。

    SELECT
  campaign.name,
  metrics.clicks,
  segments.month
FROM campaign
WHERE segments.date > '2022-02-01'
  AND segments.date < '2022-03-01'

ISO 8601 日期

您可以使用 YYYY-MM-DD (ISO 8601) 格式指定日期和日期范围，例如：

WHERE segments.date BETWEEN '2022-06-01' AND '2022-06-30'

WHERE segments.date >= '2022-06-01' AND segments.date <= '2022-06-30'

对于需要时间段的核心日期细分（segments.week、segments.month、segments.quarter），您可以将 = 运算符与时间段的第一天搭配使用，例如：

WHERE segments.month = '2022-06-01'

预定义日期

您还可以使用以下预定义的日期和日期范围：

预定义日期
TODAY 仅限今天。
YESTERDAY 仅限昨天。
LAST_7_DAYS 过去 7 天（不包含今天）。
LAST_BUSINESS_WEEK 上个 5 天工作周（周一至周五）。
THIS_MONTH 当月所有日期。
LAST_MONTH 上个月所有日期。
LAST_14_DAYS 过去 14 天（不包括今天）。
LAST_30_DAYS 过去 30 天（不包括今天）。
THIS_WEEK_SUN_TODAY 上周日到当天的时间段。
THIS_WEEK_MON_TODAY 上周一到当天的时间段。
LAST_WEEK_SUN_SAT 从上周日开始为期 7 天的时间段。
LAST_WEEK_MON_SUN 从上周一开始为期 7 天的时间段。

示例：

WHERE segments.date DURING LAST_30_DAYS

零指标

执行查询时，您可能会遇到某些实体的指标值为零的情况。 了解如何在查询中处理零指标。

UNKNOWN 枚举类型

如果返回的资源具有 UNKNOWN 枚举数据类型，则表示该类型在相应 API 版本中不受完全支持。这些资源可能是通过其他接口创建的。例如，Search Ads 360 界面中引入了新的广告系列或广告，但您查询的 API 版本尚不支持该广告系列或广告。

当资源类型为 UNKNOWN 时，您仍然可以选择指标，但需要注意以下几点：

  • 以后可能会支持 UNKNOWN 类型的资源，但它可能会无限期地保持 UNKNOWN 状态。

  • 类型为 UNKNOWN 的新对象可能会随时出现。这些对象是向后兼容的，因为枚举值已可用。我们会在此次变更中引入资源，以便您准确了解自己的账号。UNKNOWN 资源之所以可能会显示，是因为您的账号通过其他界面进行了新活动，或者是因为某个资源不再正式受支持。

  • UNKNOWN 资源可能附有详细的指标，您可以查询这些指标。

  • UNKNOWN 资源通常会在 Search Ads 360 界面中完全显示。