Skip to content

Latest commit

 

History

History
292 lines (209 loc) · 13.4 KB

BingAdsAccountSelector.md

File metadata and controls

292 lines (209 loc) · 13.4 KB
Raw
title description author ms.author ms.service ms.topic
BingAdsAccountSelector object
Contains the methods used in multi-account scripts for filtering the list of accounts that you have access to.
jonmeyers
jonmeyers
bing-ads-scripts
article

BingAdsAccountSelector

Contains the methods for filtering and ordering the list of accounts the user has access to. For information about selectors, see Selectors.

Example usage:

    var accounts = AccountsApp.accounts()
        .withCondition("Name CONTAINS_IGNORE_CASE 'PARTIAL ACCOUNT NAME GOES HERE'")
        .get();

    while (accounts.hasNext()) {
        var account = accounts.next();
    }

Methods

Method Name Return Type Description
executeInParallel(string functionName, string optionalCallbackFunctionName) void Executes the function for each account that the selector returns.
executeInParallel(string functionName, string optionalCallbackFunctionName, string optionalInput) void Executes the function for each account that the selector returns.
forDateRange(Object dateFrom, Object dateTo) BingAdsAccountSelector Applies the start and end dates for selecting performance metrics.
forDateRange(string dateRange) BingAdsAccountSelector Applies the predefined date range for selecting performance metrics.
get BingAdsAccountIterator Gets an iterator used to iterate through the list of accounts.
orderBy(string orderBy) BingAdsAccountSelector Applies the specified ordering to the selected accounts.
withAccountNumbers(string[] accountNumbers) BingAdsAccountSelector Gets accounts with the specified account numbers.
withCondition(string condition) BingAdsAccountSelector Applies filter criteria to the accounts.
withIds(string[] ids) BingAdsAccountSelector Gets accounts with the specified IDs.
withLimit(int limit) BingAdsAccountSelector Gets the top n accounts that match the selection criteria.

executeInParallel(string functionName, string optionalCallbackFunctionName)

Executes the function for each account that the selector returns. After the function is executed for all selected accounts, Scripts calls the optional callback function.

Note

The script may execute a maximum of 50 accounts in parallel each time the script runs. You may call this method once or multiple times but the total number of accounts all calls process must not exceed 50. If a call exceeds the 50 account maximum for the script, none of the accounts in the call are executed. To limit the number of accounts the selector returns, consider using the withLimit or withIds method.

The functionName function may return a value as a string. To return a complex object, use the JSON.stringify method to convert the object to a string. You can then use the JSON.parse method to convert the string back into an object. If your function returns a value, you must specify a callback function to capture the return values. The following shows the callback function's signature. The returned values are passed as an array of ExecutionResult objects.

function myCallback(ExecutionResult[] results)

The following example shows how to process the returned values in the callback function.

function myCallback(results) {
    for (var result of results) {
        var object = JSON.parse(result.getReturnValue());
    }
}

Because this method does not return a BingAdsAccountSelector object, make sure this method is the last selector method in the call chain.

For an example, see Discovering disapproved ads.

Arguments

Name Type Description
functionName string The name of the function to execute for each account that the selector returns. The currentAccount method identifies the account the function is processing.
optionalCallbackFunctionName string Optional. The name of the function to execute after all accounts finish executing the functionName function. This function executes only one time.

Returns

Type Description
void Returns nothing.

executeInParallel(string functionName, string optionalCallbackFunctionName, string optionalInput)

Executes the function for each account that the selector returns. After the function executes for all selected accounts, Scripts calls the optional callback function.

Note

The script may execute a maximum of 50 accounts in parallel each time the script runs. You may call this method once or multiple times but the total number of accounts all calls process must not exceed 50. If a call exceeds the 50 account maximum for the script, none of the accounts in the call are executed. To limit the number of accounts the selector returns, consider using the withLimit or withIds method.

The functionName function may return a value as a string. To return a complex object, use the JSON.stringify method to convert the object to a string. You can then use the JSON.parse method to convert the string back into an object. If your function returns a value, you must specify a callback function to capture the return values. The following shows the callback function's signature. The returned values are passed as an array of ExecutionResult objects.

function myCallback(ExecutionResult[] results)

The following example shows how to process the returned values in the callback function.

function myCallback(results) {
    for (var result of results) {
        var object = JSON.parse(result.getReturnValue());
    }
}

If you pass the optional input parameter, the following shows the signature of the functionName function.

function myFunction(string optionalInput)

Because this method does not return a BingAdsAccountSelector object, make sure this method is the last selector method in the call chain.

For an example, see Discovering disapproved ads.

Arguments

Name Type Description
functionName string The name of the function to execute for each account that the selector returns. The currentAccount method identifies the account the function is processing.
optionalCallbackFunctionName string Optional. The name of the function to execute after all accounts finish executing the functionName function. This function executes only one time.
optionalInput string Optional. Input to pass to the functionName function.

Returns

Type Description
void Returns nothing.

forDateRange(Object dateFrom, Object dateTo)

Applies the start and end dates for selecting performance metrics.

[!INCLUDEdate-range-objects]

Arguments

Name Type Description
dateFrom Object The start date of the date range that specifies the performance data to include in the selector.
dateTo Object The end date of the date range that specifies the performance data to include in the selector.

Returns

Type Description
BingAdsAccountSelector Selector with date range applied.

forDateRange(String dateRange)

Applies the predefined date range for selecting performance metrics.

[!INCLUDEdate-range-constants]

[!INCLUDEdate-range-conditions-message]

Arguments

Name Type Description
dateRange String The predefined date range string that specifies the performance data to include in the selector. The predefined date range string is case sensitive.

Returns

Type Description
BingAdsAccountSelector Selector with date range applied.

get

Gets an iterator used to iterate through the list of accounts.

Returns

Type Description
BingAdsAccount An iterator used to iterate through the selected accounts.

orderBy(string orderBy)

Applies the specified ordering to the selected accounts.

Specify the orderBy parameter in the form, "columnName orderDirection" where:

  • columnName is one of the supported columns.
  • orderDirection is the order to sort the results in. Set to ASC to order the results in ascending order or DESC to order the results in descending order. The default is ASC.

For example, the following call returns results in ascending order by Clicks.

selector = selector.orderBy("Clicks");

[!INCLUDEorder-by-limit]

Arguments

Name Type Description
orderBy string The ordering to apply.

Returns

Type Description
BingAdsAccountSelector Selector with ordering applied.

withAccountNumbers(string[] accountNumbers)

Gets accounts with the specified account numbers.

Arguments

Name Type Description
accountNumbers string[] An array of account numbers. For limits, see Script execution limits.

Returns

Type Description
BingAdsAccountSelector Selector with the account numbers applied.

withCondition(String condition)

Applies filter criteria to the accounts.

Specify the condition parameter in the form, "columnName operator value" where:

[!INCLUDEoperators]

Supported columns for account filtering. The column names are case sensitive.

The following are the performance metrics columns you may specify.

Column Type Example Microsoft Advertising web UI filter
ClickConversionRate double withCondition("ClickConversionRate > 0.25") Conv. Rate
Clicks long withCondition("Clicks >= 33") Clicks
ConvertedClicks long withCondition("ConvertedClicks >= 10") Conv.
Cost double withCondition("Cost > 3.25")

The cost is in the account's currency.		 Spend
Ctr double withCondition("Ctr > 0.05")

The CTR is in the range 0..1, so use 0.05 for a 5% CTR.		 CTR
Impressions long withCondition("Impressions > 10") Impr.

The following are the account properties you may specify.

Column Type Example Microsoft Advertising web UI filter
CurrencyCode string The currency code of the currency used by the account. For example, USD for United States dollar.

withCondition("CurrencyCode = USD")
ManagerCustomerId string The customer ID of the user managing the accounts.

withCondition("ManagerCustomerId = '123456789'")
Name string The name of a managed account.

withCondition("Name CONTAINS_IGNORE_CASE 'foo'")

Arguments

Name Type Description
condition string The condition to add to the selector.

Returns

Type Description
BingAdsAccountSelector Selector with the condition applied.

withIds(string[] ids)

Gets accounts with the specified IDs.

[!INCLUDEwith-ids-chaining] For example, the following call selects only account 33333.

AccountsApp.accounts()
    .withIds(['11111', '22222', '33333'])
    .withIds(['33333', '44444', '55555']);
    .get();

Arguments

Name Type Description
ids string[] An array of account IDs. For limits, see Script execution limits.

Returns

Type Description
BingAdsAccountSelector Selector with the IDs applied.

withLimit(int limit)

Gets the top n accounts that match the selection criteria.

Arguments

Name Type Description
limit int The number of accounts to return. The actual number may be less.

Returns

Type Description
BingAdsAccountSelector Selector with limit applied.

See also