查询结构

您可以向 GoogleAdsService Search 或 SearchStream 方法发送资源、细分和指标字段的查询。如需使用 Google Ads 查询语言构建查询，请使用该 语言语法。如需大致了解 Google Ads 查询语言，请参阅Google Ads 查询语言概览。查询由多个子句组成：

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

子句使用字段名称、资源名称、运算符、条件和排序，帮助您选择正确的数据。将这些子句组合成一个查询后，您可以向 Google Ads API 发送请求。

子句

以下部分介绍了每个 Google Ads 查询语言子句的用途和语法。

SELECT

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
  • 查询不可选择的字段。这些字段的 selectable 元数据属性标记为 false。
  • 选择重复字段的属性。这些字段的 is_repeated 元数据属性标记为 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 模式（或使用 BETWEEN value AND value、IS NULL 或 IS NOT NULL）。查询中可以不包含 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。

查询 返回的资源 
SELECT
  campaign.name,
  customer.id
FROM campaign
  • 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

无

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
  • 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'
上一页
查询语法
下一页
日期范围