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

此页面由 Cloud Translation API 翻译。

查询结构和子句

一个查询由多个子句组成：SELECT， FROM, WHERE, ORDER BY、 LIMIT, 和 PARAMETERS。

子句使用字段名称、资源名称、运算符、条件、和 ordering 合并为一个查询请求。

简而言之，要构建查询，您需要：

指定要从中检索数据的资源。
添加字段和指标以定义要返回的数据。
添加细分以对结果进行分组。
添加归因资源以隐式联接相关资源数据。
对结果进行过滤、排序和限制。

`SELECT` 子句

SELECT 子句：

是查询中的 required 子句。
指定要在请求中提取的一组字段。
获取以英文逗号分隔的资源字段、自定义列和自定义列表 Floodlight 变量、细分字段和指标，并返回响应。

此示例查询展示了如何选择 campaign 的属性资源：

SELECT
  campaign.id,
  campaign.name
FROM campaign

多字段类型

您可以在同一请求中请求不同的字段类型。

以下示例查询展示了包含以下各项的组合的单个查询：

资源字段：campaign.id、campaign.name、bidding_strategy.id 和 bidding_strategy.name。
细分字段：segments.device 和 segments.date。
指标字段：metrics.impressions 和 metrics.clicks。

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

请参阅细分详细了解如何细分搜索报告。

主要资源字段

通常，您可以在 SELECT 中包含主要资源字段子句，但这是可选的（不必需）。

此示例查询使用主要资源字段 (ad_group.status) 仅过滤结果。

SELECT campaign.id
FROM ad_group
WHERE ad_group.status = PAUSED

自定义 Floodlight 变量

您可以使用自定义 Floodlight 变量的 id。

在本例中，查询包含一个 ID 为 123454321 的自定义变量，广告系列资源。

SELECT
  conversion_custom_metrics.id[123454321]
FROM campaign

SELECT
  conversion_custom_dimensions.id[123454321]
FROM campaign

自定义列

您可以使用自定义列的 ID 在 SELECT 子句中添加自定义列。

在此示例中，查询包含一个 ID 为 12345678 的自定义列，广告系列资源。

SELECT
  custom_columns.id[12345678]
FROM campaign

了解如何获取自定义列 ID。

指标字段

您可以为给定资源选择指标字段，而不包含任何其他 SELECT 子句中的资源的字段。

此示例查询为 campaign 选择 impressions 和 clicks 指标资源。

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

请参阅 metrics 您可以在查询中使用的指标字段的列表。

细分字段

您可以选择细分字段，而无需指定随附的资源字段或指标在 SELECT 子句中。

以下示例查询会按设备对结果进行细分。

SELECT segments.device
FROM campaign

请参阅 segments 您可以在查询中使用的细分字段列表。

禁止的字段

在 SELECT 子句中不能使用以下字段：

不可选择字段，即具有 Selectable 元数据的字段属性标记为 false。
重复字段，即具有 Repeated 元数据属性的字段已标记为true。
不适用于 FROM 子句中的指定资源的字段。某些资源的属性不能同时选择。仅限部分资源以便提供所有指标和细分的子集
细分或指标不兼容。如需了解详情，请参阅细分信息。

如需了解更多详情，请参阅参考文档。

FROM 子句

FROM 子句：

是一个必需子句，用于 SearchAds360Service （Search 和 SearchStream 方法）。
对 SearchAds360FieldService 的查询不应包含此属性。
指定查询返回的主要资源。
只能指定一个资源。
定义可在查询的所有其他子句中使用的字段。

。

归因资源

如果归因资源可用，它们就会隐式与您在 FROM 子句中指定的资源。您只需为其添加属性 SELECT 子句以返回它们的值。

此示例查询会返回广告组 ID 和广告系列 ID，因为 campaign 是 ad_group 资源的归因资源。

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

`resource_name` 字段

FROM 子句中主要资源的 resource_name 字段始终为返回。

在此示例查询中，响应中包含 ad_group.resource_name （即使它未在查询中明确选中）：

SELECT ad_group.id
FROM ad_group

归因资源的 resource_name 字段为选择至少一个字段时返回的值。

在此示例查询中，campaign.resource_name 将包含在回答，因为选择了“campaign.id”：

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE 子句

WHERE 子句：

是查询中的可选子句。
指定用于过滤和细分请求数据的条件。条件采用以下格式：FIELD_NAME OPERATOR VALUE（用空格）。
可包含多个条件，以 AND 分隔符分隔。

此示例查询展示了如何使用 WHERE 子句返回 impressions 特定时间段的指标：

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

请参阅细分详细了解如何细分搜索报告。

请参阅日期范围，详细了解如何指定日期范围。

按“`resource_name`”字段过滤

您可以使用 resource_name 字段对数据进行过滤或排序。

此示例查询使用 campaign.resource_name 字段来过滤结果按给定广告系列划分：

SELECT
  campaign.id,
  campaign.name
FROM campaign
WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'

多重条件

您可以结合使用多个条件来过滤数据。

此示例查询请求所有广告系列的 clicks 指标数量过去 30 天内移动设备上的 impressions 个指标。

SELECT
  campaign.id,
  campaign.name,
  segments.device,
  metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
  AND segments.device = MOBILE
  AND segments.date DURING LAST_30_DAYS

请参阅细分详细了解如何细分报告。

大小写区分

按字符串值过滤时，每个运算符的默认区分大小写在正确过滤结果方面起着重要作用。

下表显示了每个运算符的默认大小写区分规则。

默认区分大小写
`=/!=`	`Case sensitive`
`IN/NOT IN`	`Case sensitive`
`LIKE/NOT LIKE`	`Case insensitive`
`CONTAINS (...)`	`Case sensitive`
`REGEXP_MATCH/NOT REGEXP_MATCH`	`Case sensitive`

您可以使用 (?i) 修饰符来更改 REGEXP_MATCH 和 NOT REGEXP_MATCH 不区分大小写，例如：

SELECT campaign.id
FROM campaign
WHERE campaign.name REGEXP_MATCH "(?i).*test.*"

如需查看完整的列表，请参阅查询语法参考。运算符。

核心日期细分

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

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

以下示例查询为 segments.date 字段指定了 DURING LAST_30_DAYS 在 WHERE 子句中：

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

请参阅细分 >核心日期细分有关使用核心日期细分的信息。

禁止的过滤

不允许对以下内容进行过滤：

未选择的细分字段（核心日期细分除外）。
任何消息类型的字段，但基元（例如 Int64Value、 StringValue 等）。
任何消息类型的重复字段（基元除外）的特性上（例如 Int64Value、StringValue 等）。

ORDER BY 子句

ORDER BY 子句：

是查询中的可选子句。
指定返回结果的顺序。排序遵循以下图案：FIELD_NAME ORDERING_OPTION（用空格分隔）。
允许使用两个选项：ASC（升序）或 DESC（降序）。默认值为升序。

此示例查询按点击次数降序对广告系列进行排序（从高到低）：

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC

多个订单

您可以使用英文逗号分隔的 ORDER BY 子句中指定多个字段列表。结果会按照您在查询。

此示例查询选择广告组数据，并按升序对结果进行排序先按广告系列名称排序，然后按展示次数降序排列，以及然后按点击次数降序排列：

SELECT
  campaign.name,
  ad_group.name,
  metrics.impressions,
  metrics.clicks
FROM ad_group
ORDER BY
  campaign.name,
  metrics.impressions DESC,
  metrics.clicks DESC

结合使用排序和限制

您可以将 ORDER BY 子句与 LIMIT 子句结合使用，优化您的搜索结果。

此示例查询返回在过去 30 天：

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 5

禁止的订单

不允许按以下内容进行排序：

按未选择资源的属性。
按未选择的指标。
未选择的细分受众群。
对于这些字段类型： <ph type="x-smartling-placeholder">
- MESSAGE
- 重复字段
- 重复字段的属性。

LIMIT 子句

LIMIT 子句：

是查询中的可选子句。
用于限制查询返回的结果数。

举例来说，如果您只对部分示例或结果摘要。

以下示例查询将结果总数限制为 50：

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

PARAMETERS 子句

PARAMETERS 子句用于指定请求的元参数。

包含草稿

include_drafts 参数用于控制草稿实体是否包含在结果。默认值为 false。如需包含草稿实体，请将其设置为 true。

此示例查询会返回广告系列草稿和常规广告系列：

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

忽略未选择的`resource_name`

借助 omit_unselected_resource_names 参数，您可以排除您的 resource_name 字段中未明确请求的所有资源的 SELECT 子句。默认值为 false。如果您将此参数设置为 true，建议您明确请求主要资源的资源名称以及 SELECT 子句中的任何已归因资源。

此示例查询既不返回 campaign.resource_name，也不返回 customer.resource_name 字段，因为它们未包含在 SELECT 中子句：

SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

此示例查询会返回 campaign.resource_name 字段，因为它是在 SELECT 子句中明确请求：

SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true

更改指标中使用的币种

借助 metrics_currency 参数，您可以指定要使用的币种。（在计算 SELECT 子句中包含的指标时）。默认设置是为账号使用本地货币。如果您将参数，您需要使用由 3 个字符组成的 ISO 4217 货币代码。例如：USD、EUR。

此示例查询以。

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"

此示例查询会返回以智利比索 (CLP) 为单位的 cost_micros 指标。

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"
PARAMETERS metrics_currency = "CLP"

了解详情

查询语法