MccApp.​ManagedAccountSelector

Fetches accounts (not including AdWords Express accounts). Supports filtering and sorting.

Typical usage:

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

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

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 MccApp.ManagedAccountSelector Sets a predefined date range onto the selector.
forDateRange MccApp.ManagedAccountSelector Sets a custom date range onto the selector.
get MccApp.ManagedAccountIterator Fetches the requested accounts and returns an iterator.
orderBy MccApp.ManagedAccountSelector Specifies the ordering of the resulting entities.
withCondition MccApp.ManagedAccountSelector Adds the specified condition to the selector in order to narrow down the results.
withIds MccApp.ManagedAccountSelector Restricts this selector to return only customers with the given customer IDs.
withLimit MccApp.ManagedAccountSelector Specifies limit for the selector to use.

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

NameTypeDescription
dateRange String Date range to set onto the selector.

Return values:

TypeDescription
MccApp.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
MccApp.ManagedAccountSelector The selector with date range applied.

get()

Fetches the requested accounts and returns an iterator.

Return values:

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

NameTypeDescription
orderBy String Ordering to apply.

Return values:

TypeDescription
MccApp.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, AveragePosition):
    <  >
  • 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")
AveragePosition Double withCondition("AveragePosition > 7.5")
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:

NameTypeDescription
condition String Condition to add to the selector.

Return values:

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

 MccApp.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 long[] Array of customer IDs.

Return values:

TypeDescription
MccApp.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
MccApp.ManagedAccountSelector The selector with limit applied.

Send feedback about...

AdWords Scripts
AdWords Scripts
Need help? Visit our support page.