AdsManagerApp.​ManagedAccountSelector

Fetches ManagedAccounts. Supports filtering and sorting.

Typical usage:

var accountSelector = AdsManagerApp
    .accounts()
    .withCondition("customer_client.currency_code = 'USD'")
    .orderBy("customer_client.descriptive_name DESC");

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

Related:

• ManagedAccountIterator
• ManagedAccount

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.
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 "[e-mail]";
• 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 "[e-mail]";
• 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.
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.

Filtering on stats is not supported for upgraded extensions (only for *attached* upgraded extensions). As such, this method no longer does anything.

Deprecated. Accounts are no longer able to be ordered or filtered by date range.

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.

Filtering on stats is not supported for upgraded extensions (only for *attached* upgraded extensions). As such, this method no longer does anything.

Deprecated. Accounts are no longer able to be ordered or filtered by date range.

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("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.

Stats can no longer be used to order accounts.

Arguments:

Name	Type	Description
orderBy	String	Ordering to apply.

Return values:

Type	Description
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):

  =  !=  (NOT) (LIKE | CONTAINS | REGEXP_MATCH)

• For Enumeration columns (ones that can only take one value from a predefined list, such as Status):

  =  !=  IN ()  NOT IN ()

• For StringSet columns (e.g. customer_client.applied_labels):

  CONTAINS ALL ()  CONTAINS ANY ()  CONTAINS NONE ()

Conditions using IN, NOT IN, CONTAINS ALL, CONTAINS ANY and CONTAINS NONE 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.

Stats can no longer be used to filter accounts.

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.

Arguments:

Name	Type	Description
ids	Object[]	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.

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:

Name	Type	Description
resourceNames	String[]	Array of account resource names.

Return values:

Type	Description
AdsManagerApp.ManagedAccountSelector	The selector restricted to the given resource names.