在 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 通常能够提供更好的性能，因为它消除了请求各个页面所需的往返网络时间。我们建议对超过 10,000 行的所有报告使用 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

发出请求

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

此请求包含发送到 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

下面是 HTTP POST 请求中包含的对 searchStream 的报告定义的完整示例：

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 等字段。

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

资源字段列

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

“细分”列

对于给定资源，并非所有细分字段都可供选择。

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

指标列

对于给定资源，并非所有指标字段都可供选择。

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

对资源进行细分

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

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

可通过以下图片选择：

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

segments 页面为每个 segments 字段包含一个可选择的选项，其中列出了所有兼容的资源字段、metrics 字段以及您可以添加到 SELECT 子句中的其他 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 子句中指定多个细分。对于 FROM 子句中指定的主要资源的实例的每个组合，以及每个选定 segment 字段的 value，在响应中都包含一个 SearchAds360Row 对象。

例如，以下查询将为 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

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

核心日期细分规则：

  • 您可以在 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 资源可能附加了详细指标，您可以查询这些指标。
  • 在 Search Ads 360 界面中，UNKNOWN 资源通常完全可见。