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 都包含有关所请求字段的详细信息。

如需详细了解查询结构，请参阅 Query Structure 和 Google Ads Query Language Grammar。

查询资源属性

以下是针对广告系列资源属性的基本查询示例，说明了如何返回广告系列 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 且按广告系列 ID 排序时展示次数超过 1000 次的广告系列。每个生成的 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 参考文档。

最佳做法

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

根据查询结果进行修改

在查询给定资源时，您可以立即将返回的结果作为对象，对其进行修改，然后将其发回给该资源服务中的 mutate 方法。以下是一个示例工作流程： 1. 针对当前处于 PAUSED 状态且展示次数超过 1000 的所有广告系列执行查询。 1. 从响应中每个 GoogleAdsRow 的 campaign 字段获取 Campaign 对象。 1. 将每个广告系列的状态从 PAUSED 更改为 ENABLED。 1. 使用修改后的广告系列调用 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 查询语言的示例GoogleAdsService。基本操作 文件夹中也包含了各种示例，例如 GetCampaigns、GetKeywords 和 SearchForGoogleAdsFields。

下一页
查询语法