Google Ads 查询语言

Google Ads 查询语言可查询以下内容的 Google Ads API:

使用 GCP 控制台提供的资源及其相关属性、细分和指标
GoogleAdsService SearchSearchStream
GoogleAdsService 查询的结果是一系列 GoogleAdsRow 实例,其中每个 GoogleAdsRow 代表一个资源。如果请求了任何属性或指标,则该行还包含这些字段。如果请求了任何细分,则响应还会为每个细分-资源元组额外显示一行。
有关 中可用字段和资源的元数据
GoogleAdsFieldService

此服务提供可查询字段的目录,其中包含有关其兼容性和类型的详细信息。

GoogleAdsFieldService 查询的结果是 GoogleAdsField 实例的列表,其中每个 GoogleAdsField 都包含有关所请求字段的详细信息。

查询资源的特性

以下是针对广告系列资源属性的基本查询,说明了如何返回广告系列 ID、名称和状态:

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign
ORDER BY campaign.id

此查询按广告系列 ID 进行排序。每个生成的 GoogleAdsRow 表示一个填充了所选字段(包括该指定广告系列的 resource_name)的 campaign 对象。

如需了解还有哪些其他字段可用于广告系列查询,请参阅 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 且展示次数超过 1, 000 次的广告系列(按广告系列 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 都表示一个填充了所选广告系列属性和所选出价策略属性 bidding_strategy.namecampaign 对象。

如需了解哪些归因资源可用于广告系列查询,请参阅 Campaign 参考文档

根据查询结果进行更改

在查询给定资源时,您可以立即将这些返回的结果作为对象进行修改,然后将它们发送回该资源的服务中的 mutate 方法。以下是一个示例工作流程:

  1. 对当前状态为 PAUSED 且展示次数大于 1,000 的所有广告系列执行查询。
  2. 从响应中每个 GoogleAdsRowcampaign 字段中获取 Campaign 对象。
  3. 将每个广告系列的状态从 PAUSED 更改为 ENABLED
  4. 使用修改后的广告系列调用 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> 替换为资源(例如 customercampaign)或字段(例如 campaign.idmetrics.impressionsad_group.id)。

如需查看可查询字段的列表,请参阅 GoogleAdsField 文档

代码示例

客户端库提供了在 GoogleAdsService 中使用 Google Ads 查询语言的示例。基本操作文件夹中提供了 GetCampaignsGetKeywordsSearchForGoogleAdsFields 等示例。报告文件夹中有一个 GetKeywordStats 示例。