What are selectors?
Selectors let you apply filter and sort criteria when retrieving Microsoft Advertising entities such as keywords and campaigns. Selectors provide functionality roughly equivalent to SQL
ORDER BY clauses. Selectors include the following methods:
withCondition() — Use to specify conditions that entities must meet to be selected. This is equivalent to a SQL
withCondition('Name STARTS_WITH "Contoso"')
You may apply one or more conditions to a selector. Specifying multiple conditions is considered an AND operation. For example, the entity is selected only if condition A is true AND condition B is true.
withIds() — Use to specify the IDs of entities to select. This is equivalent to a SQL
forDateRange() — Use to return entities with performance data that match the specified date range. If a condition specifies a metric column, you must include
forDateRangein the selector's chain.
orderBy() — Use to order the entities that the selector returns by a specified field. This is equivalent to a SQL
withLimit() — Use to return at most the specified number of entities. This is equivalent to a SQL
Because each method returns the selector with the filter criteria applied, you may chain together (using dot notation) multiple conditions to refine the filter criteria. For example:
var selector = AdsApp.campaigns() .withCondition("ClickConversionRate > 0.5") .withCondition("Cost > 4.0") .forDateRange("LAST_WEEK") .withLimit(10);
To improve script performance, use specific filter conditions to ensure that you retrieve only the entities you want. After getting the selector, call the
get() method to retrieve an iterator that you use to iterate through the list of entities.
var campaigns = selector.get();
var campaigns = AdsApp.campaigns() .withCondition("ClickConversionRate > 0.5") .withCondition("Cost > 4.0") .forDateRange("LAST_WEEK") .withLimit(10) .get();
The following is the list of selectors.