AdsManagerApp.ManagedAccountSelector

Fetches accounts. Supports filtering and sorting.

Typical usage:

 var accountSelector = AdsManagerApp
     .accounts()
     .withCondition("Impressions > 100")
     .forDateRange("LAST_MONTH")
     .orderBy("Clicks DESC");

 var accountIterator = accountSelector.get();
 while (accountIterator.hasNext()) {
   var account = accountIterator.next();
 }

Note: Google Ads Express accounts are not included.

Methods:

Member	Type	Description
executeInParallel	`void`	Executes the function specified by `functionName` on each ManagedAccount that the `AccountSelector` matches.
executeInParallel	`void`	Executes the function specified by `functionName` on each ManagedAccount that the `AccountSelector` matches.
forDateRange	`AdsManagerApp.ManagedAccountSelector`	Sets a predefined date range onto the selector.
forDateRange	`AdsManagerApp.ManagedAccountSelector`	Sets a custom date range onto the selector.
get	`AdsManagerApp.ManagedAccountIterator`	Fetches the requested accounts and returns an iterator.
orderBy	`AdsManagerApp.ManagedAccountSelector`	Specifies the ordering of the resulting entities.
withCondition	`AdsManagerApp.ManagedAccountSelector`	Adds the specified condition to the selector in order to narrow down the results.
withIds	`AdsManagerApp.ManagedAccountSelector`	Restricts this selector to return only customers with the given customer IDs.
withLimit	`AdsManagerApp.ManagedAccountSelector`	Specifies limit for the selector to use.

`executeInParallel(functionName, optionalCallbackFunctionName)`

The function specified by functionName can optionally return a string. For example,

return "Account name";
return "$100.22";
return "client@companyA.com";
return "5";

JSON.stringify(value) can be used to convert a value to JSON and then return the string. For example,

 return JSON.stringify({value:10, list:[1,2,3,4,5,6], name: "Joe Smith"});

These will be passed into the callback function in a list of ExecutionResult objects. If JSON.stringify(value) is used in the callback function, the value can then be turned back into a JavaScript object with JSON.parse(returnValue). For example,

 function optionalCallbackFunctionName(results) {
   for (var i = 0; i < results.length; i++) {
     object = JSON.parse(results[i].getReturnValue());
   }
 }

executeInParallel can operate simultaneously on up to 50 accounts. If the selector contains more than 50 accounts, an exception is thrown and no accounts are processed. You can limit the number of accounts for the executeInParallel method using accountSelector.withLimit(accountLimit).

The signature for the optionalCallbackFunctionName should be:

 function callbackMethod(/*ExecutionResult[]*/ results) {

 }

Returns nothing.

Arguments:

Name	Type	Description
functionName	`String`	The name of the function to execute for each ManagedAccount in the selector.
optionalCallbackFunctionName	`String`	Optional. The name of the function to execute, in the scope of the MCC account, once processing of the accounts in the selector has completed. This function will only be executed once.

`executeInParallel(functionName, optionalCallbackFunctionName, optionalInput)`

Executes the function specified by functionName on each ManagedAccount that the AccountSelector matches. Once all the accounts have been processed, the callback function, if specified by optionalCallbackFunctionName, is executed once. The input, if specified by optionalInput, will be passed into the function specified by functionName. For example,

 accountSelector.executeInParallel(functionName, optionalCallbackFunctionName,
                                   optionalInput)

The input can then be accessed in the function like this:

 function functionName(optionalInput) {
   Logger.log(optionalInput);
 }

The function specified by functionName can optionally return a string. For example,

return "Account name";
return "$100.22";
return "client@companyA.com";
return "5";

JSON.stringify(value) can be used to convert a value to JSON and then return the string. For example,

 return JSON.stringify({value:10, list:[1,2,3,4,5,6], name: "Joe Smith"});

 function optionalCallbackFunctionName(results) {
   for (var i = 0; i < results.length; i++) {
     object = JSON.parse(results[i].getReturnValue());
   }
 }

The signature for the optionalCallbackFunctionName should be:

 function callbackMethod(/*ExecutionResult[]*/ results) {

 }

Returns nothing.

Arguments:

Name	Type	Description
functionName	`String`	The name of the function to execute for each ManagedAccount in the selector.
optionalCallbackFunctionName	`String`	Optional. The name of the function to execute, in the scope of the MCC account, once processing of the accounts in the selector has completed. This function will only be executed once.
optionalInput	`String`	Optional. A `string` that can be specified that will be passed into the function being executed for each account.

`forDateRange(dateRange)`

Sets a predefined date range onto the selector. Supported values:

TODAY, YESTERDAY, LAST_7_DAYS, THIS_WEEK_SUN_TODAY, LAST_WEEK, LAST_14_DAYS, LAST_30_DAYS, LAST_BUSINESS_WEEK, LAST_WEEK_SUN_SAT, THIS_MONTH, LAST_MONTH, ALL_TIME. Example:

 selector.forDateRange("THIS_WEEK_SUN_TODAY");

Date range must be specified if the selector has conditions or ordering for a stat field. Note that only the last date range specified for the selector will take effect.

Arguments:

Name	Type	Description
dateRange	`String`	Date range to set onto the selector.

Return values:

Type	Description
`AdsManagerApp.ManagedAccountSelector`	The selector with date range applied.

`forDateRange(dateFrom, dateTo)`

Sets a custom date range onto the selector. Both parameters can be either an object containing year, month, and day fields, or an 8-digit string in YYYYMMDD form. For instance, March 24th, 2013 is represented as either {year: 2013, month: 3, day: 24} or "20130324". The date range is inclusive on both ends, so forDateRange("20130324", "20130324") sets the range of one day.

Date range must be specified if the selector has conditions or ordering for a stat field. Note that only the last date range specified for the selector will take effect.

Arguments:

Name	Type	Description
dateFrom	`Object`	Start date of the date range.
dateTo	`Object`	End date of the date range.

Return values:

Type	Description
`AdsManagerApp.ManagedAccountSelector`	The selector with date range applied.

`get()`

Fetches the requested accounts and returns an iterator.

Return values:

Type	Description
`AdsManagerApp.ManagedAccountIterator`	Iterator of the requested accounts.

`orderBy(orderBy)`

Specifies the ordering of the resulting entities. orderBy parameter can have one of the following forms:

orderBy("Cost") - orders results by Cost, in ascending order.
orderBy("Ctr ASC") - orders results by Ctr, in ascending order.
orderBy("MaxCpc DESC") - orders results by MaxCpc, in descending order.

See ManagedAccountSelector.withCondition(String) for enumeration of columns that can be used.

orderBy() may be called multiple times. Consider the following example:

 selector = selector.forDateRange("LAST_14_DAYS")
     .orderBy("Clicks DESC")
     .orderBy("CTR ASC");

The results will be ordered by Clicks in descending order. Results with equal Clicks value will be ordered by Ctr in ascending order.

If a stats column is used in the ordering, date range must be specified via ManagedAccountSelector.forDateRange(String) or ManagedAccountSelector.forDateRange(Object, Object).

LabelNames column cannot be used for ordering.

Arguments:

Name	Type	Description
orderBy	`String`	Ordering to apply.

Return values:

Type	Description
`AdsManagerApp.ManagedAccountSelector`	The selector with ordering applied.

`withCondition(condition)`

Adds the specified condition to the selector in order to narrow down the results.

Multiple conditions may be added to the same selector:

 selector = selector.forDateRange("LAST_MONTH")
     .withCondition("Clicks > 5")
     .withCondition("Impressions > 100");

All specified conditions are AND-ed together. The above example will retrieve entities that observed over 100 impressions AND more than 5 clicks.

The parameter to be passed into this method must be of the following form:

 "COLUMN_NAME OPERATOR VALUE"

Operators

The operator that can be used in a condition depends on the type of column.

For Integer and Long columns (e.g. Impressions, Clicks):
< <= > >= = !=
For Double columns (e.g. Ctr):
< >

For String columns (e.g. Name):
= != STARTS_WITH STARTS_WITH_IGNORE_CASE CONTAINS CONTAINS_IGNORE_CASE DOES_NOT_CONTAIN DOES_NOT_CONTAIN_IGNORE_CASE

For Enumeration columns (ones that can only take one value from a predefined list, such as Status):
= != IN [] NOT_IN []
For Array columns (e.g. LabelNames):
CONTAINS DOES_NOT_CONTAIN

e.g., LabelNames CONTAINS 'ACCOUNT_LABEL'

Conditions using IN, NOT_IN, CONTAINS, and DOES_NOT_CONTAIN operators look as follows:

 withCondition("ColumnName IN [Value1, Value2]")

Operators are case-sensitive: starts_with won't work.

Columns

All column names are case-sensitive, and so are all values of enumerated columns (such as Status).

Column	Type	Example
*Stats*
AverageCpc	Double	`withCondition("AverageCpc < 1.45")`
AverageCpm	Double	`withCondition("AverageCpm > 0.48")`
Clicks	Long	`withCondition("Clicks >= 21")`
ConversionRate	Double	`withCondition("ConversionRate > 0.1")`
Conversions	Long	`withCondition("Conversions <= 4")`
Cost	Double	`withCondition("Cost > 4.48")`. The value is in the currency of the account.
Ctr	Double	`withCondition("Ctr > 0.01")`. Note that Ctr is returned in `0..1` range, so 5% Ctr is represented as 0.05.
CurrencyCode	String	`withCondition("CurrencyCode = 'USD'")`. The three-letter ISO 4217-formatted currency code of the account.
DateTimeZone	String	`withCondition("DateTimeZone = 'America/New_York'")`. The local timezone ID for the account.
Impressions	Long	`withCondition("Impressions != 0")`
LabelNames	Array	`withCondition("LabelNames CONTAINS 'priority'")`
ManagerCustomerId	Account ID	`withCondition("ManagerCustomerId IN ['123-456-7890']")` or `withCondition("ManagerCustomerId IN [1234567890]")`. Used to select child accounts belonging to a specific submanager.
Name	String	`withCondition("Name = 'Sunny Sky'")`. The name used by the manager to refer to the client.

If a stats column is used in the condition, date range must be specified via ManagedAccountSelector.forDateRange(String) or ManagedAccountSelector.forDateRange(Object, Object).

Arguments:

Name	Type	Description
condition	`String`	Condition to add to the selector.

Return values:

Type	Description
`AdsManagerApp.ManagedAccountSelector`	The selector with the condition applied.

`withIds(ids)`

Restricts this selector to return only customers with the given customer IDs.

 var customerIds = ['123-456-7890', '234-567-8901', '345-678-9012'];
 selector = selector.withIds(customerIds);

The resulting selector can be further refined by applying additional conditions to it. The ID-based condition will then be AND-ed together with all the other conditions, including any other ID-based conditions. So, for instance, the following selector:

 AdsManagerApp.accounts()
    .withIds(['123-456-7890', '234-567-8901', '345-678-9012'])
    .withIds(['345-678-9012', '456-789-0123', '567-890-1234']);

will only get the customer with ID 345-678-9012, since it would be the only customer that satisfies both ID conditions.

The customer IDs can be passed in either as numbers, or as hyphen-separated strings. The following two calls do the same thing:

 accounts.withIds(['123-456-7890', '234-567-8901', '345-678-9012']);
 accounts.withIds([1234567890, 2345678901, 3456789012]);

Note that only single-customer (non-MCC) accounts can be selected by ID. To select all accounts under a submanager, instead specify a condition on ManagerCustomerId; e.g. withCondition("ManagerCustomerId IN ['123-456-7890']")

Arguments:

Name	Type	Description
ids	`long[]`	Array of customer IDs.

Return values:

Type	Description
`AdsManagerApp.ManagedAccountSelector`	The selector restricted to the given IDs.

`withLimit(limit)`

Specifies limit for the selector to use. For instance, withLimit(50) returns only the first 50 entities.

Arguments:

Name	Type	Description
limit	`int`	How many entities to return.

Return values:

Type	Description
`AdsManagerApp.ManagedAccountSelector`	The selector with limit applied.

AdsManagerApp.​ManagedAccountSelector

Methods:

executeInParallel(functionName, optionalCallbackFunctionName)

Arguments:

executeInParallel(functionName, optionalCallbackFunctionName, optionalInput)

Arguments:

forDateRange(dateRange)

Arguments:

Return values:

forDateRange(dateFrom, dateTo)

Arguments:

Return values:

get()

Return values:

orderBy(orderBy)

Arguments:

Return values:

withCondition(condition)

Operators

Columns

Arguments:

Return values:

withIds(ids)

Arguments:

Return values:

withLimit(limit)

Arguments:

Return values:

AdsManagerApp.ManagedAccountSelector

`executeInParallel(functionName, optionalCallbackFunctionName)`

`executeInParallel(functionName, optionalCallbackFunctionName, optionalInput)`

`forDateRange(dateRange)`

`forDateRange(dateFrom, dateTo)`

`get()`

`orderBy(orderBy)`

`withCondition(condition)`

`withIds(ids)`

`withLimit(limit)`