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 都表示一个 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 且展示次数超过 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 且展示次数超过 1, 000 次的广告系列。不过，此查询会按日期对数据进行细分。这会导致每个生成的 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. 执行查询，找出展示次数大于 1000 的所有 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 和 v26）中都相同，但可查询资源、细分、指标和报告行为的目录因主要版本而异。在目标 API 版本端点查询 GoogleAdsFieldService，以检查该版本的字段和兼容性规则：

  • “最终到达网址扩展”素材资源视图：
    • 购物广告系列支持（v26 及更高版本）： final_url_expansion_asset_view 除了支持效果最大化广告系列和搜索广告系列之外，还支持购物广告系列 (campaign.advertising_channel_type = 'SHOPPING')。对于购物广告系列，您可以选择 ad_group 字段并按其进行过滤，但不能选择 asset_group 字段。
    • 可选指标（v25 及更高版本）：查询 final_url_expansion_asset_view 会返回视图的所有可选指标。在 v24 及更早版本中，响应仅包含效果最大化广告系列的 metrics.conversions 和 metrics.conversions_value，以及搜索广告系列的 metrics.impressions。
  • 生命周期目标资源：在 v25 及更高版本中，所有生命周期目标（新客户获取、客户留存和忠诚度留存）均通过统一的 goal 和 campaign_goal_config 资源进行查询，取代了 customer_lifecycle_goal 和 campaign_lifecycle_goal（在 v24 及更低版本中，这些资源用于新客户获取目标，而 goal 和 campaign_goal_config 用于客户留存目标）。
  • 应用广告系列的购物产品报告：在 v24 及更高版本中，除了购物广告系列、效果最大化广告系列、需求开发广告系列和视频广告系列之外，shopping_product 资源还会返回应用广告系列的产品行（在 v23 中，应用广告系列会从 shopping_product 结果中排除）。
  • 特定于版本的资源、细分和指标：
    • v26 及更高版本：包含 search_lift_keyword_bundle 资源、campaign.lift_measurement_config、local_services_lead.campaign、segments.search_lift_keyword_bundle、segments.search_property 和搜索次数提升情况指标（例如 metrics.relative_search_lift、metrics.normalized_incremental_searches、metrics.search_lift_cost_micros 和 metrics.search_lift_impressions）。
    • 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 等示例。

下一页
查询语法