選擇器

程式設計師可透過選取器建構查詢,擷取要求的 Google Ads 實體。使用選取器,可以縮小擷取實體的清單範圍並排序。大多數選取器都有下列方法:

withCondition()
為選取器新增條件。如果使用多個條件,這些條件會以 AND 運算子連結,也就是說,選取器只會傳回符合「所有」指定條件的實體。
withIds()
新增一組 ID 做為條件。系統會以 AND 運算子連結 ID 條件與所有其他條件。
forDateRange()
如果條件或排序子句參照「統計資料」欄位 (例如 CTR 或曝光次數),則為必要屬性。如果您要求所有曝光次數超過 100 次的廣告活動, Google Ads 指令碼需要知道要查看的日期範圍。
orderBy()
指定傳回實體的順序。
withLimit()
將傳回的實體數量限制為指定值。與 orderBy() 搭配使用時特別實用,可擷取「昨天曝光次數最多的 10 個關鍵字」等項目。根據預設,所有選取器都會將上限設為 50,000。如要提高上限,請手動指定上限。

這些方法可以按任何順序呼叫。但 orderBy() 是例外情形,因為呼叫順序確實會影響結果:多次呼叫這個方法會指定多個排序子句,且這些子句會依序套用。請參考以下程式碼片段:

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

結果會按點擊次數遞減排序。如果點擊次數值相同,系統會依遞增順序排列點閱率。

可以將對選取器方法的呼叫串連在一起。以下程式碼

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

請參閱最佳做法,瞭解如何有效使用選取器。