Google Ads 查询语言可查询以下内容的 Google Ads API:
- 使用
GoogleAdsService
Search 或 SearchStream- GoogleAdsService 查询会返回一个
GoogleAdsRow
实例列表,其中每个GoogleAdsRow
表示一个资源。如果请求了任何属性或指标,则该行也会包含这些字段。如果请求了任何细分,则响应还会针对每个细分资源元组额外显示一行。 - 有关 中的可用字段和资源的元数据
GoogleAdsFieldService
此服务提供可查询字段的目录,其中包含有关其兼容性和类型的详细信息。
GoogleAdsFieldService
查询的结果是一个GoogleAdsField
实例列表,其中每个GoogleAdsField
都包含有关所请求字段的详细信息。
查询资源的特性
以下是对广告系列资源属性的基本查询,说明了如何返回广告系列 ID、名称和状态:
SELECT
campaign.id,
campaign.name,
campaign.status
FROM campaign
ORDER BY campaign.id
此查询按广告系列 ID 排序。每个生成的 GoogleAdsRow
都将表示填充了所选字段的 campaign
对象(包括该给定广告系列的 resource_name
)。
如需了解哪些其他字段可用于广告系列查询,请参阅 Campaign
参考文档。
查询指标
除了给定资源的选定属性之外,您还可以查询相关指标:
SELECT
campaign.id,
campaign.name,
campaign.status,
metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
AND metrics.impressions > 1000
ORDER BY campaign.id
此查询仅过滤出状态为 PAUSED
且展示次数超过 1000 次且按广告系列 ID 排序的广告系列。每个生成的 GoogleAdsRow
都会有一个填充了所选指标的 metrics
字段。
如需查看可查询指标的列表,请参阅 Metrics
文档。
查询细分
除了给定资源的选定属性之外,您还可以查询相关细分:
SELECT
campaign.id,
campaign.name,
campaign.status,
metrics.impressions,
segments.date,
FROM campaign
WHERE campaign.status = 'PAUSED'
AND metrics.impressions > 1000
AND segments.date during LAST_30_DAYS
ORDER BY campaign.id
与查询指标类似,此查询仅过滤出状态为 PAUSED
且展示次数超过 1000 的广告系列;不过,此查询会按日期细分数据。这样会生成每个生成的 GoogleAdsRow
,它表示一个广告系列的元组和日期 Segment
。请务必注意,细分会拆分选定的指标,并按 SELECT 子句中的每个细分进行分组。
如需查看可查询细分的列表,请参阅 Segments
文档。
查询相关资源的特性
在给定资源的查询中,您或许可以联接其他相关资源(如果有)。这些相关资源称为“归因资源”。您可以通过在查询中选择属性来隐式与归因资源联接。
SELECT
campaign.id,
campaign.name,
campaign.status,
bidding_strategy.name
FROM campaign
ORDER BY campaign.id
此查询不仅会选择广告系列属性,还会从各个所选广告系列中提取相关属性。生成的每个 GoogleAdsRow
表示一个 campaign
对象,其中填充了选定的广告系列属性和选定的出价策略属性 bidding_strategy.name
。
如需了解哪些归因资源可用于广告系列查询,请参阅 Campaign
参考文档。
根据查询结果执行 Mutate 操作
在查询给定资源时,您可以立即将这些返回的结果作为对象进行修改,然后将它们发送回该资源服务中的 mutate 方法。以下是一个示例工作流程:
- 针对当前处于
PAUSED
状态且展示次数大于 1000 的所有广告系列执行查询。 - 从响应中每个
GoogleAdsRow
的campaign
字段中获取Campaign
对象。 - 将每个广告系列的状态从
PAUSED
更改为ENABLED
。 - 使用修改后的广告系列调用
CampaignService.MutateCampaigns
以更新它们。
字段元数据
发送到 GoogleAdsFieldService
的查询用于检索字段元数据。此信息可用于了解如何在查询中结合使用这些字段。由于数据可通过 API 获取,并且提供验证或构建查询所需的元数据,因此开发者能够以编程方式执行这些操作。以下是典型的元数据查询:
SELECT
name,
category,
selectable,
filterable,
sortable,
selectable_with,
data_type,
is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"
您可以将此查询中的 <INSERT_RESOURCE_OR_FIELD>
替换为资源(例如 customer
或 campaign
)或字段(例如 campaign.id
、metrics.impressions
或 ad_group.id
)。
如需查看可查询字段的列表,请参阅 GoogleAdsField
文档。
代码示例
客户端库提供了有关如何在 GoogleAdsService
中使用 Google Ads 查询语言的示例。基本操作文件夹中包含 GetCampaigns
、GetKeywords
和 SearchForGoogleAdsFields
等示例。reporting 文件夹中有一个 GetKeywordStats
示例。