Edit

UserListSelector

  • Article

Contains the methods for filtering and ordering a list of user lists in the account. For information about selectors, see Selectors.

Methods

Method Name Return Type Description
get UserListIterator Gets an iterator used to iterate through the list of user lists.
orderBy(string orderBy) UserListSelector Applies the specified ordering to the selected user lists.
withCondition(string condition) UserListSelector Applies filter criteria to the user lists.
withIds(string[] ids) UserListSelector Gets user lists with the specified IDs.
withLimit(int limit) UserListSelector Gets the top n user lists that match the selection criteria.

get

Gets an iterator used to iterate through the list of user lists.

Returns

Type Description
UserListIterator An iterator used to iterate through the selected user lists.

orderBy(string orderBy)

Applies the specified ordering to the selected user lists.

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

  • columnName is one of the [supported columns](#supported-user list-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 the user list's name.

selector = selector.orderBy("Name");

Selectors support ordering entities by one field only. You may not order the list of entities by field x, and within x by field y, and so on. If you specify more than one orderBy() call in a chain or in separate selector calls, Scripts orders the list of entities using the field specified in the last orderBy() call. 

Arguments

Name Type Description
orderBy string The ordering to apply.

Returns

Type Description
UserListSelector Selector with ordering applied.

withCondition(String condition)

Applies filter criteria to the user lists.

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

  • columnName is one of the [supported columns](#supported-user list-columns).
  • operator is one of the supported operators.

Operators

The operator that you use depends on the column's type. Operators are case-sensitive. For example, use STARTS_WITH instead of starts_with.

Operators for columns that contain integers and long values:

<
<=
>
>=
=
!=

Operators for columns that contain double values:

<
>

Operators for columns that contain string values:

=
!=
STARTS_WITH
STARTS_WITH_IGNORE_CASE
CONTAINS
CONTAINS_IGNORE_CASE
DOES_NOT_CONTAIN
DOES_NOT_CONTAIN_IGNORE_CASE

Operators for columns that contain enumeration values:

=
!=
IN []
NOT_IN []

Operators for columns that contain an array of strings:

CONTAINS_ALL
CONTAINS_ANY
CONTAINS_NONE

Supported columns for user list filtering. The column names are case sensitive.

Column Type Example
Description string The user list's description.

withCondition("Description = 'foo'")
MembershipLifeSpan int How far back in time (number of days) Microsoft Advertising should look for actions that match this user list definition.

withCondition("MembershipLifeSpan > 10")
Name string The user list's name.

withCondition("Name = 'foo'")
SizeForAudienceNetwork long The user list's size in the Audience network.

withCondition("SizeForAudienceNetwork > 1000")
SizeForSearch long The user list's size in the Audience network.

withCondition("SizeForSearch > 1000")
Type string The user list's derived type. Possible case-sensitive values are:
  • CUSTOM
  • CUSTOMER_LIST
  • IN_MARKET
  • LOGICAL
  • PRODUCT
  • RULE_BASED
  • SIMILAR
This example returns only customer lists.

withCondition("Type = CUSTOMER_LIST")

Arguments

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

Returns

Type Description
UserListSelector Selector with the condition applied.

withIds(string[] ids)

Gets user lists with the specified IDs.

You may apply one or more conditions to a selector. A chain of conditions is considered an AND operation. For example, the entity is selected only if condition A is true AND condition B is true. For example, the following call selects only user list 33333.

AdsApp.userLists()
    .withIds(['11111', '22222', '33333'])
    .withIds(['33333', '44444', '55555']);

Arguments

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

Returns

Type Description
UserListSelector Selector with the IDs applied.

withLimit(int limit)

Gets the top n user lists that match the selection criteria.

Arguments

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

Returns

Type Description
UserListSelector Selector with limit applied.

See also