AdsManagerApp.​ManagedAccountSelector

Stay organized with collections Save and categorize content based on your preferences.
Fetches accounts. Supports filtering and sorting.

Typical usage:

 var accountSelector = AdsManagerApp
     .accounts()
     .withCondition("metrics.impressions > 100")
     .forDateRange("LAST_MONTH")
     .orderBy("metrics.clicks DESC");

 var accountIterator = accountSelector.get();
 while (accountIterator.hasNext()) {
   var account = accountIterator.next();
 }
Related: Note: Google Ads Express accounts are not included.

Methods:

MemberTypeDescription
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.
withResourceNames AdsManagerApp.ManagedAccountSelector Restricts this selector to return only accounts with the given Google Ads API resource names.

executeInParallel(functionName, optionalCallbackFunctionName)

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 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:

NameTypeDescription
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"});

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:

NameTypeDescription
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, LAST_14_DAYS, LAST_30_DAYS, LAST_BUSINESS_WEEK, LAST_WEEK_SUN_SAT, LAST_WEEK_MON_SUN, THIS_WEEK_MON_TODAY, THIS_WEEK_SUN_TODAY, LAST_MONTH, THIS_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:

NameTypeDescription
dateRange String Date range to set onto the selector.

Return values:

TypeDescription
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:

NameTypeDescription
dateFrom Object Start date of the date range.
dateTo Object End date of the date range.

Return values:

TypeDescription
AdsManagerApp.ManagedAccountSelector The selector with date range applied.

get()

Fetches the requested accounts and returns an iterator.

Return values:

TypeDescription
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("customer_client.currency_code") - orders results by currency code, in ascending order.
  • orderBy("customer_client.time_zone ASC") - orders results by time zone, in ascending order.
  • orderBy("customer_client.descriptive_name DESC") - orders results by descriptive name, 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
     .orderBy("customer_client.currency_code DESC")
     .orderBy("customer_client.descriptive_name ASC");

The results will be ordered by currency code in descending order. Results with equal currency code value will be ordered by descriptive name in ascending order.

LabelNames column cannot be used for ordering.

Arguments:

NameTypeDescription
orderBy String Ordering to apply.

Return values:

TypeDescription
AdsManagerApp.ManagedAccountSelector The selector with the 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
     .withCondition("customer_client.descriptive_name contains 'test'")
     .withCondition("customer_client.currency_code = 'USD'");
All specified conditions are AND-ed together. The above example will retrieve accounts whose name contains 'test' and rely on the US Dollar.

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. customer_client.id):
    <  <=  >  >=  =  !=
  • For String columns (e.g. customer_client.descriptive_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. customer_client.applied_labels):
    CONTAINS  DOES_NOT_CONTAIN

    e.g., customer_client.applied_labels CONTAINS 'customers/123/labels/456'

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
customer_client.currency_code String withCondition("customer_client.currency_code = 'USD'"). The three-letter ISO 4217-formatted currency code of the account.
customer_client.time_zone String withCondition("customer_client.time_zone = 'America/New_York'"). The local timezone ID for the account.
customer_client.applied_labels Array withCondition("customer_client.applied_labels CONTAINS 'customers/123/labels/456'")
customer_client.descriptive_name String withCondition("customer_client.descriptive_name = 'Sunny Sky'"). The name used by the manager to refer to the client.

Arguments:

NameTypeDescription
condition String Condition to add to the selector.

Return values:

TypeDescription
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]);

Arguments:

NameTypeDescription
ids Object[] Array of customer IDs.

Return values:

TypeDescription
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:

NameTypeDescription
limit int How many entities to return.

Return values:

TypeDescription
AdsManagerApp.ManagedAccountSelector The selector with limit applied.

withResourceNames(resourceNames)

Restricts this selector to return only accounts with the given Google Ads API resource names.
 const accountResourceNames = [
   'customers/1234567890/customerClients/111',
   'customers/1234567890/customerClients/222',
   'customers/1234567890/customerClients/333',
 ];
 selector = selector.withResourceNames(accountResourceNames);

The resulting selector can be further refined by applying additional conditions to it. The resource name condition will then be AND-ed together with all the other conditions.

The selector can only support up to 10,000 resource names. If more than 10,000 resource names are specified, the corresponding get() call will fail with a runtime error.

Arguments:

NameTypeDescription
resourceNames String[] Array of account resource names.

Return values:

TypeDescription
AdsManagerApp.ManagedAccountSelector The selector restricted to the given resource names.