查询结构

您可以将针对资源、细分和指标字段的查询发送到 GoogleAdsService.Search。要使用 Google Ads 查询语言构建查询，您需要使用语言语法。一个查询由许多子句组成，包括：

SELECT
FROM
WHERE
ORDER BY
LIMIT
PARAMETERS

这些子句会使用字段名称、资源名称、运算符、条件和排序，帮您选出正确的数据。在将它们合并为一个查询后，就可以使用 Google Ads API 发出请求。让我们看看如何使用每个子句。

子句

SELECT

SELECT 子句指定要在请求中获取的一组字段。SELECT 会获取以英文逗号分隔的资源字段、细分字段和指标列表，然后在响应中返回值。SELECT 子句在查询中是必需子句。

要获取广告系列的 ID 和名称，您可以使用以下查询：

SELECT
  campaign.id,
  campaign.name
FROM campaign

在单个请求中，可以请求不同的字段类型，例如：

资源字段
- campaign.id
- campaign.name
- ad_group.name
细分字段
- segments.device
指标
- metrics.impressions
- metrics.clicks

SELECT
  ad_group.name,
  ad_group.id,
  segments.device,
  metrics.impressions,
  metrics.clicks
FROM ad_group

以下情况不允许使用 SELECT 子句：

查询 Selectable 元数据属性已标记为 false 的字段。
选择重复字段的属性。重复字段的元数据中的 isRepeated 属性会标记为 true。您可以通过我们的文档或 GoogleAdsFieldService 了解相关信息。

FROM

FROM 子句可指定用于选择字段的主要资源。相关服务会使用该资源按需连接其他资源和细分数据。在 FROM 子句中，只可指定一个资源。FROM 子句是查询中的必需子句，但使用 GoogleAdsFieldService 时不应指定该子句。

您可以从其他资源中选择字段，而无需在 FROM 子句中明确定义相应资源。这些字段与 FROM 子句中的资源隐式连接。对于 FROM 子句中的资源，如果其 segments 属性中包含连接的资源，则连接的资源将充当细分。如果连接的资源位于 AttributedResources 属性中，则选择该资源不会对指标产生任何影响。并非所有资源都有归因资源。在以下示例中，您可以同时从广告组中请求广告组 ID 和广告系列 ID：

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

系统会始终返回主要资源的 resource_name 字段。在以下示例中，尽管未在查询中明确选定 ad_group.resource_name，它也将包含在响应中：

SELECT ad_group.id
FROM ad_group

如果至少选择了一个字段，则其他资源也是如此。例如，campaign.resource_name 将包含在以下查询的响应中：

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE

借助 WHERE 子句，您可以在为相关请求过滤数据时指定要应用的条件。当使用 WHERE 子句时，可以指定一个或多个条件，并使用 AND 将其分隔开。每个条件都应遵循 field_name Operator value 这一格式。WHERE 子句在查询中是可选子句。

以下示例演示了如何使用 WHERE 返回指定时间段的指标：

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

您可以结合使用多个条件来过滤数据。以下示例将请求过去 30 天内在移动设备上获得展示的所有广告系列的点击次数。

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

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

ORDER BY

ORDER BY 子句用于指定结果的返回顺序。这样一来，您就可以根据字段名称按升序或降序排列相关数据。每次排序都按 field_name 后跟 ASC 或 DESC 的形式指定。如果既未指定 ASC，也未指定 DESC，则顺序默认为 ASC。ORDER BY 子句在查询中是可选子句。

以下查询按点击次数从高到低顺序对返回的广告系列进行排序：

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

LIMIT

LIMIT 子句用于指定要返回的结果数量。如果您只对摘要信息感兴趣，这个子句会非常有用。

例如，LIMIT 可用于限制以下查询的结果总数：

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

PARAMETERS

PARAMETERS 子句用于指定请求的元参数。这些参数可能会影响返回的行类型。

目前仅支持一种元参数：

include_drafts：设置为 true 可允许返回草稿实体。默认值为 false。

例如，PARAMETERS 可用于提取广告系列草稿以及常规广告系列：

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

语言规则

除了各子句的示例外，Google Ads 查询语言还具有以下行为：

主要资源字段无需位于查询的 SELECT 子句中。例如，您可能只想使用一个或多个主要资源字段来过滤数据：
```
SELECT campaign.id
FROM ad_group
WHERE ad_group.status = PAUSED
```
可以为给定资源专门选择指标；无需在查询中使用资源中的其他字段：
```
SELECT
  metrics.impressions,
  metrics.clicks,
  metrics.costMicros
FROM campaign
```
可以选择细分字段，而不包含任何附带的资源字段或指标：
```
SELECT segments.device FROM campaign
```

resource_name 字段（例如 campaign.resource_name）可用于执行数据过滤或数据排序：

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

查询语法

日期范围