新版 Search Ads 360 Reporting API 现已发布。您可以加入 searchads-api-announcements Google 网上论坛，及时了解即将发布的增强功能和版本。

此页面由 Cloud Translation API 翻译。

在 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 配额和限制：无论结果是分页还是流式传输，单个查询或报告都将计为 1 项操作。

搜索查询示例

以下示例查询会按广告系列返回账号在过去 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 等字段。

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

“资源字段”列

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

“细分”列

并非所有细分字段都可以通过给定资源进行选择。

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

“指标”列

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

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

细分资源

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

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

可通过以下方式选择

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

segments 页面针对每个 segments 字段提供了一个可展开的 Selectable with，其中列出了所有兼容的资源字段、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 子句中指定多个细分。响应包含一个 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

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

核心日期细分规则：

您可以在 WHERE 子句中使用核心日期字段，而无需将其包含在 SELECT 子句中。如果您愿意，也可以在两个子句中添加该字段。

以下示例查询会按日期范围按广告系列名称返回 clicks 指标。请注意，SELECT 子句中不包含 segments.date。
```
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

0 个指标

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

未知枚举类型

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

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

系统日后可能会支持类型为 UNKNOWN 的资源，但该资源也可能会永久保持 UNKNOWN 类型。
类型为 UNKNOWN 的新对象随时都可能出现。由于枚举值已可用，因此这些对象向后兼容。我们会在有资源可用时，随此变更一并介绍这些资源，以便您准确了解自己的账号。UNKNOWN 资源可能会出现，原因可能是您的账号通过其他接口产生了新活动，也可能是某个资源不再受正式支持。
UNKNOWN 资源可能附加了您可以查询的详细指标。
UNKNOWN 资源通常会在 Search Ads 360 界面中完整显示。