程式設計師可透過選取器建構查詢,擷取要求的 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。
請參閱最佳做法,瞭解如何有效使用選取器。