Google Ads API is returning to beta status. Please read our blog post for more details.

查询结构

您可以将针对资源、细分和指标字段的查询发送到 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 后跟 ASCDESC 的形式指定。如果既未指定 ASC,也未指定 DESC,则顺序默认为 ASCORDER 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'