针对资源、细分和指标字段的查询可以发送到 GoogleAdsService
Search 或 SearchStream 方法。要使用 Google Ads 查询语言构建查询,您需要使用语言语法构建。查询由许多子句组成:
SELECT
FROM
WHERE
ORDER BY
LIMIT
PARAMETERS
这些子句会使用字段名称、资源名称、运算符、条件和排序,帮您选出正确的数据。合并为单个查询后,即可使用 Google Ads API 发出请求。
条款
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
由于以下限制,SELECT
子句中可能不允许使用某些字段:
- 查询不可选择的字段。这些字段会将其
Selectable
元数据属性标记为false
。 - 选择重复字段的属性。这些字段会将其
isRepeated
元数据属性标记为true
。 - 选择
FROM
子句中给定资源不可用的字段。某些资源的属性不能同时选择,而且FROM
子句中的资源也将只能选择部分指标和细分。 - 选择互不兼容的细分或指标。有关详情,请参阅细分部分。
如需了解与上述条件相关的信息,请参阅我们的参考文档或 GoogleAdsFieldService
。
FROM
FROM
子句指定要返回的主要资源。FROM
子句中的资源定义哪些字段可用于指定查询的所有其他子句。在 FROM
子句中只能指定一项资源。在对 GoogleAdsService
Search 或 SearchStream 方法的查询中,必须使用 FROM
子句,但在使用 GoogleAdsFieldService
时,不应指定该子句。
虽然对于给定查询,FROM
子句中只能有 1 项资源,但“归因资源”中的字段也可能可用。这些资源与 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
满足上述条件的所有细分均包括:segment.date、segment.week、segments.month、segments.quarter 和 segment.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
子句,您可以为请求指定元参数。这些参数可能会影响返回的行类型。
目前支持以下元参数:
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
。
shortcuts_unselected_resource_names 示例 | |
---|---|
SELECT campaign.name, customer.id FROM campaign |
Returned resources:campaign.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'