Google Ads 查询语言

主要术语

资源
Google Ads 中的实体，例如 campaign 或 ad_group。
Segment
用于对数据进行分组的维度，例如 segments.date 或 segments.device。 如果 SELECT 子句中包含细分，并且还包含指标，则指标会按细分进行拆分。
指标
一种效果衡量指标，例如 metrics.impressions 或 metrics.clicks。
提供方信息资源
一种隐式联接到 FROM 子句中主资源的资源，可让您选择其属性以及主资源属性。

查询资源或元数据信息

Google Ads 查询语言可以向 Google Ads API 查询以下类型的信息：

  • 使用 GoogleAdsService Search 或 SearchStream 的资源及其相关属性、细分和指标：GoogleAdsService 查询的结果是一个 GoogleAdsRow 实例列表，其中每个 GoogleAdsRow 都表示一个资源。

    如果请求了任何属性或指标，则相应行也会包含这些字段。如果请求了任何细分，则响应还会针对每个细分资源元组显示一个额外的行。

  • 有关 GoogleAdsFieldService 中可用字段和资源的元数据：此服务提供可查询字段的目录，其中包含有关其兼容性和类型的详细信息。

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

如需详细了解查询结构，请参阅查询结构和 Google Ads 查询语言语法。

查询资源属性

以下示例展示了如何针对广告系列资源的属性发出基本查询，以返回广告系列 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 且展示次数超过 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 都表示一个广告系列和日期段的元组。细分会拆分所选指标，并按 SELECT 子句中的每个细分进行分组。

如需查看可查询的细分列表，请参阅 Segments 文档。

在针对给定资源的查询中，您可以根据需要与其他相关资源进行联接。这些相关资源称为“提供方信息资源”。您可以在查询中选择一个属性，以针对归因资源进行隐式联接。

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

此查询不仅会选择广告系列属性，还会从所选的每个广告系列中提取相关属性。每个生成的 GoogleAdsRow 都表示一个 campaign 对象，其中填充了所选的广告系列属性以及所选的出价策略属性 bidding_strategy.name。

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

最佳做法

  • 仅选择所需的字段，以避免响应时间过长和超时。
  • 在开发和测试期间使用 LIMIT，以避免处理大型结果集。
  • 在 WHERE 子句中应用过滤条件，以最大限度地减少数据传输和响应大小。
  • 在构建复杂查询之前，使用 GoogleAdsFieldService 检查字段兼容性和数据类型。
  • 请注意，某些字段（尤其是涉及大量数据或复杂计算的字段）可能会增加查询费用。

根据查询结果进行变异

在查询给定资源时，您可以立即将返回的结果作为对象，对其进行修改，然后将其发送回相应资源服务的 mutate 方法。以下是一个工作流示例：

  1. 针对所有展示次数超过 1,000 的 PAUSED 广告系列执行查询。
  2. 从响应中每个 GoogleAdsRow 的 campaign 字段获取 Campaign 对象。
  3. 将每个广告系列的状态从 PAUSED 更改为 ENABLED。
  4. 使用修改后的广告系列和相应的 FieldMask 调用 CampaignService.MutateCampaigns 以更新广告系列。

字段元数据

发送到 GoogleAdsFieldService 的查询旨在检索字段元数据。此信息可用于了解如何在查询中一起使用这些字段。由于数据可从 API 获取，并且 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 文档。

版本特定的差异

虽然 Google Ads 查询语言的语法、子句和运算符在所有受支持的 Google Ads API 版本（v23、v24 和 v25）中都是相同的，但可查询的资源、细分、指标和报告行为的目录因主要版本而异。在目标 API 版本端点查询 GoogleAdsFieldService，以检查该版本的字段和兼容性规则：

  • 生命周期目标资源：在 v25 及更高版本中，所有生命周期目标（新客户获取、客户留存和忠诚度留存）都通过统一的 goal 和 campaign_goal_config 资源进行查询，取代了 customer_lifecycle_goal 和 campaign_lifecycle_goal（在 v24 及更早版本中，这两个资源与 goal 和 campaign_goal_config 一起用于“新客户获取”目标，而 goal 和 campaign_goal_config 用于“客户留存”目标）。
  • 最终到达网址扩展素材资源视图指标：在 v25 及更高版本中，查询 final_url_expansion_asset_view 会返回视图的所有可选择指标。在 v24 及更早版本中，对于效果最大化广告系列，响应仅包含 metrics.conversions 和 metrics.conversions_value；对于搜索广告系列，响应仅包含 metrics.impressions。
  • 应用广告系列的购物产品报告：在 v24 及更高版本中，shopping_product 资源除了返回购物广告系列、效果最大化广告系列、需求开发广告系列和视频广告系列的产品行之外，还会返回应用广告系列的产品行（在 v23 中，shopping_product 结果中不包含应用广告系列）。
  • 特定于版本的资源、细分和指标：
    • v25 及更高版本：包含提升效果评测资源（例如 lift_measurement_config）、细分（例如 segments.ad_sub_format_type 和 segments.loyalty_membership）以及 YouTube 互动指标（metrics.youtube_likes、metrics.youtube_comments 和 metrics.youtube_shares）。移除了 local_services_lead.contact_details.email（可在 v24 及更早版本中选择）。
    • v24 及更高版本：包括 cart_data_sales_view 资源、shopping_performance_view 上的 segments.conversion_attribution_event_type、segments.mobile_device_platform 和 performance_max_placement_view 上的 segments.ad_network_type。移除了 campaign.video_brand_safety_suitability（已替换为 customer.video_brand_safety_suitability）、campaign_budget 上的 segments.ad_sub_network_type 以及 ad_group_asset、campaign_asset 和 customer_asset 上的 segments.click_type（仅在 v23 中可选择）。
  • 细粒度日期回溯错误代码：如果查询按 segments.date、segments.week 或 segments.hour 进行细分（或按不足一个月的时间范围进行过滤），且时间范围超出 37 个月的回溯期，则在 v24 及更高版本中返回 DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED（在 v23 中返回 DateRangeError.UNKNOWN）。如需了解详情，请参阅日期范围。

代码示例

客户端库中包含在 GoogleAdsService 中使用 Google Ads 查询语言的示例。基本操作文件夹包含 GetCampaigns、GetKeywords 和 SearchForGoogleAdsFields 等示例。

下一页
查询语法