查询结构

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

  • SELECT
  • FROM
  • WHERE
  • ORDER BY
  • LIMIT
  • PARAMETERS

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

条款

视频：GAQL 字段兼容性

选择

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

以下示例查询展示了如何为给定资源选择属性：

SELECT
  campaign.id,
  campaign.name
FROM campaign

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

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

  • 资源字段

    • campaign.id
    • campaign.name

  • 资源字段

    • bidding_strategy.id
    • bidding_strategy.name

  • 细分字段

    • segments.device
    • segments.date

  • 指标

    • metrics.impressions
    • metrics.clicks

由于存在以下限制，某些字段可能不允许在 SELECT 子句中使用：

  • 查询不可选择的字段。这些字段的 Selectable 元数据属性将标记为 false。
  • 选择重复字段的属性。这些字段的 isRepeated 元数据属性将标记为 true。
  • 选择 FROM 子句中不适用于指定资源的字段。某些资源的属性无法同时选择，此外，FROM 子句中的资源仅提供部分指标和细分。
  • 选择彼此不兼容的细分或指标。如需详细了解这一点，请参阅细分部分。

如需了解与上述条件相关的信息，请参阅我们的参考文档或 GoogleAdsFieldService。

FROM

FROM 子句可指定将返回的主要资源。FROM 子句中的资源定义了给定查询的所有其他子句可以使用哪些字段。在 FROM 子句中，只可指定一个资源。在对 GoogleAdsService Search 或 SearchStream 方法的查询中，FROM 子句是必需子句。不过，使用 GoogleAdsFieldService 时，不应指定 FROM 子句。

虽然在给定查询的 FROM 子句中只能存在一个资源，但归因资源的字段也可能可用。这些资源与 FROM 子句中的资源隐式联接，因此您只需将它们的属性添加到 SELECT 子句中即可返回它们的值。并非所有资源都有归因资源。在以下示例中，您可以同时从广告组中请求广告组 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

WHERE 子句中的细分必须位于 SELECT 子句中，但以下日期细分（称为核心日期细分）除外：

  • segments.date
  • segments.week
  • segments.month
  • segments.quarter
  • segments.year

在以下查询中，请注意 segments.date 已被选中。 由于此细分是核心日期细分，因此需要在 WHERE 子句中提供由核心日期细分组成的有限日期范围。

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

满足上述条件的所有细分受众群为：segments.date、segments.week、segments.month、segments.quarter 和 segments.year。如果选择了上述任何细分，则必须在 WHERE 子句中使用至少一个细分。

在过滤时，请务必注意运算符是否区分大小写。如需了解详情，请参阅区分大小写。

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

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

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

例如，以下查询会提取广告系列草稿以及常规广告系列：

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

将 omit_unselected_resource_names 设置为 true，以防止返回响应中每种资源类型的资源名称，除非在 SELECT 子句中明确请求。默认设置为 false。

omit_unselected_resource_names 示例
SELECT
  campaign.name,
  customer.id
FROM campaign
 		Returned resources:
campaign.resource_name
customer.resource_name
omit_unselected_resource_names 默认为 false，因此系统会返回所有 resource_name 字段。 
SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true
 		Returned resources:
无。
omit_unselected_resource_names 指定为 true campaign.resource_name 和 customer.resource_name 不属于 SELECT 子句。 
SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true
 		Returned resource:
campaign.resource_name
omit_unselected_resource_names 指定为 true，campaign.resource_name 作为 SELECT 子句的一部分请求。

其他语言规则

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

  • 主要资源字段无需位于查询的 SELECT 子句中。例如，您可能只想使用一个或多个主要资源字段来过滤数据：

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

  • 可以为给定资源专门选择指标；无需在查询中使用资源中的其他字段：

    SELECT
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros
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'
上一页
查询语法
下一页
日期范围