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

此页面由 Cloud Translation API 翻译。

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

请阅读下文，了解如何在搜索广告中创建搜索报告 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 通常可以提供更好的性能，因为它可以消除请求各个页面所需的往返网络时间。我们建议使用 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

下面是对 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中未包含的属性子句。

例如，下面的查询仅使用SearchAds360Row campaign.id、campaign.name和campaign.status。其他属性，例如 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 资源的已归因资源。这意味着您可以在您的campaign.idcampaign.bidding_strategy_type 查询（在 FROM 子句中使用 ad_group 时）。

促成转化的资源部分会列出可用的已归因资源。非所有资源都有已归因的资源。

“资源字段”列

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

“细分”列

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

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

指标列

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

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

对资源进行细分

某些资源包含细分资源字段。该资源在 FROM 子句中。例如，如果您选择 campaign 资源字段（如下所示） campaign.name，如果在 FROM 子句中使用 campaign_budget campaign.resource_name 将自动返回并对其进行细分，因为campaign 对 campaign_budget 的资源进行细分。

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

选择方式

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

segments 页面为每个 segments 字段包含一个可展开的 Selectable with 列出所有兼容的资源字段、metrics 字段和其他 segments 您可以在 SELECT 子句中添加的字段。

细分

您可以通过添加 segments.FIELD_NAME 字段添加到查询的 SELECT 子句中。

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

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 字段的 value 值。

例如，以下查询将针对 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 个指标

在执行查询时，您可能会发现某些指标的值为 0。实体。了解如何处理查询中的 0 个指标。

UNKNOWN 枚举类型

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

如果资源的类型为 UNKNOWN，您仍然可以选择指标，但请注意以下几点：

类型为 UNKNOWN 的资源以后可能会受支持，但可能会保留无限期UNKNOWN。
类型为 UNKNOWN 的新对象随时可能出现。这些对象是向后兼容，因为枚举值已经可用。我们引入了确保所有资源可用，以便您获得准确的账号视图。之所以显示UNKNOWN资源，可能是因为您的账号活动，或由于某个不再受到正式支持。
UNKNOWN 项资源可能附加了详细的指标，查询。
UNKNOWN 资源通常在 Search Ads 360 界面中完全可见。