选择器

选择器可帮助程序员构建查询来提取所需的 Google Ads 实体。通过使用选择器,编程人员可以精简实体检索结果列表,并为其排序。大多数选择器提供以下方法:

withCondition()
向选择器添加条件。如果使用多个条件,这些条件将以 AND 关系结合在一起,也就是说,选择器将仅返回满足所有指定条件的实体。
withIds()
添加一组 ID 作为条件。基于 ID 的条件将与其他所有条件以 AND 关系结合在一起。
forDateRange()
在条件或排序子句引用统计信息字段(如“点击率”或“展示次数”)时需要。如果您请求展示次数超过 100 次的所有广告系列,Google Ads 脚本需要知道要查找的日期范围。
orderBy()
指定返回实体的排序依据。
withLimit()
将返回的实体数量限制为指定值。在与 orderBy() 结合使用时,此参数特别适合用于提取“昨天获得展示次数最多的 10 个关键字”之类的信息。默认情况下,所有选择器会将该上限设置为 50,000。您可以通过手动指定限额来增加限额。

可以按任意顺序调用这些方法。一种例外情况是 orderBy(),其调用顺序确实很重要:对此方法的多次调用将指定多个排序子句,并且这些子句将按顺序应用。请考虑以下代码段:

selector = selector.forDateRange("LAST_14_DAYS")
    .orderBy("metrics.clicks DESC")
    .orderBy("metrics.ctr ASC");

结果按 Clicks 降序排列,“点击次数”值相同的结果将按“点击率”升序排列。

对选择器方法的调用可以链在一起。以下代码

var campaignSelector = AdsApp.campaigns();
campaignSelector.withCondition("metrics.clicks > 10");
campaignSelector.withCondition("metrics.impressions > 1000");
campaignSelector.orderBy("metrics.impressions DESC");
campaignSelector.forDateRange("YESTERDAY");

可以更紧凑的方式重写:

var campaignSelector = AdsApp.campaigns()
  .withCondition("metrics.clicks > 10")
  .withCondition("metrics.impressions > 1000")
  .orderBy("metrics.impressions DESC")
  .forDateRange("YESTERDAY");

构建选择器后,可以通过调用 selector.get() 从中获取Iterator

如需了解有关高效使用选择器的提示和技巧,请参阅最佳实践