You can construct custom combinations of existing user lists as a
logical_user_list with
UserListLogicalRuleInfo
fields. The rules in the logical_user_list are ANDed, so a user must match
every rule to be considered in the list. However, each rule lets you specify
whether its operands are ANDed or ORed. In other words, you can specify whether
the user must fulfill all of the rule operands or just one of them.
In addition, rules let you specify other logical_user_list objects as
operands, effectively letting you create a tree of them. logical_user_list can
be a very powerful way of defining complex hierarchies of groups for your
targeting. You can combine lists with different AccessReason fields. However,
if access is revoked, then that UserList will be treated as a list with no
members when the rules of the logical_user_list are evaluated.
The following code shows how to create a logical_user_list containing users in
either of two basic_user_list instances:
Java
private void runExample(
GoogleAdsClient googleAdsClient, long customerId, List<Long> userListIds) {
// Adds each of the provided list IDs to a list of rule operands specifying which lists the
// operator should target.
List<LogicalUserListOperandInfo> logicalUserListOperandInfoList = new ArrayList<>();
for (long userListId : userListIds) {
String userListResourceName = ResourceNames.userList(customerId, userListId);
logicalUserListOperandInfoList.add(
LogicalUserListOperandInfo.newBuilder().setUserList(userListResourceName).build());
}
// Creates the UserListLogicalRuleInfo specifying that a user should be added to the new list if
// they are present in any of the provided lists.
UserListLogicalRuleInfo userListLogicalRuleInfo =
UserListLogicalRuleInfo.newBuilder()
// Using ANY means that a user should be added to the combined list if they are present
// on any of the lists targeted in the LogicalUserListOperandInfo. Use ALL to add users
// present on all of the provided lists or NONE to add users that aren't present on any
// of the targeted lists.
.setOperator(UserListLogicalRuleOperator.ANY)
.addAllRuleOperands(logicalUserListOperandInfoList)
.build();
// Creates the new combination user list.
UserList userList =
UserList.newBuilder()
.setName("My combination list of other user lists #" + getPrintableDateTime())
.setLogicalUserList(
LogicalUserListInfo.newBuilder().addRules(userListLogicalRuleInfo).build())
.build();
// Creates the operation.
UserListOperation operation = UserListOperation.newBuilder().setCreate(userList).build();
// Creates the service client.
try (UserListServiceClient userListServiceClient =
googleAdsClient.getLatestVersion().createUserListServiceClient()) {
// Adds the user list.
MutateUserListsResponse response =
userListServiceClient.mutateUserLists(
Long.toString(customerId), ImmutableList.of(operation));
// Prints the response.
System.out.printf(
"Created combination user list with resource name, '%s'.%n",
response.getResults(0).getResourceName());
}
}
C#
public void Run(GoogleAdsClient client, long customerId, long[] userListIds)
{
// Gets the UserListService client.
UserListServiceClient userListServiceClient =
client.GetService(Services.V13.UserListService);
// Adds each of the provided list IDs to a list of rule operands specifying which lists
// the operator should target.
List<LogicalUserListOperandInfo> logicalUserListOperandInfoList =
userListIds.Select(userListId => new LogicalUserListOperandInfo
{ UserList = ResourceNames.UserList(customerId, userListId) }).ToList();
// Creates the UserListLogicalRuleInfo specifying that a user should be added to the new
// list if they are present in any of the provided lists.
UserListLogicalRuleInfo userListLogicalRuleInfo = new UserListLogicalRuleInfo
{
// Using ANY means that a user should be added to the combined list if they are
// present on any of the lists targeted in the LogicalUserListOperandInfo. Use ALL
// to add users present on all of the provided lists or NONE to add users that
// aren't present on any of the targeted lists.
Operator = UserListLogicalRuleOperatorEnum.Types.UserListLogicalRuleOperator.Any,
};
userListLogicalRuleInfo.RuleOperands.Add(logicalUserListOperandInfoList);
LogicalUserListInfo logicalUserListInfo = new LogicalUserListInfo();
logicalUserListInfo.Rules.Add(userListLogicalRuleInfo);
// Creates the new combination user list.
UserList userList = new UserList
{
Name = "My combination list of other user lists " +
$"#{ExampleUtilities.GetRandomString()}",
LogicalUserList = logicalUserListInfo
};
// Creates the operation.
UserListOperation operation = new UserListOperation
{
Create = userList
};
try
{
// Sends the request to add the user list and prints the response.
MutateUserListsResponse response = userListServiceClient.MutateUserLists
(customerId.ToString(), new[] { operation });
Console.WriteLine("Created combination user list with resource name: " +
$"{response.Results.First().ResourceName}");
}
catch (GoogleAdsException e)
{
Console.WriteLine("Failure:");
Console.WriteLine($"Message: {e.Message}");
Console.WriteLine($"Failure: {e.Failure}");
Console.WriteLine($"Request ID: {e.RequestId}");
throw;
}
}
PHP
public static function runExample(
GoogleAdsClient $googleAdsClient,
int $customerId,
array $userListIds
) {
// Adds each of the provided list IDs to a list of rule operands specifying which lists the
// operator should target.
$logicalUserListOperandInfoList = [];
foreach ($userListIds as $userListId) {
$logicalUserListOperandInfoList[] = new LogicalUserListOperandInfo([
'user_list' => ResourceNames::forUserList($customerId, $userListId)
]);
}
// Creates the UserListLogicalRuleInfo specifying that a user should be added to the new
// list if they are present in any of the provided lists.
$userListLogicalRuleInfo = new UserListLogicalRuleInfo([
// Using ANY means that a user should be added to the combined list if they are present
// on any of the lists targeted in the LogicalUserListOperandInfo. Use ALL to add users
// present on all of the provided lists or NONE to add users that aren't present on any
// of the targeted lists.
'operator' => UserListLogicalRuleOperator::ANY,
'rule_operands' => $logicalUserListOperandInfoList
]);
// Creates the new combination user list.
$userList = new UserList([
'name' => 'My combination list of other user lists #' . Helper::getPrintableDatetime(),
'logical_user_list' => new LogicalUserListInfo([
'rules' => [$userListLogicalRuleInfo]
])
]);
// Creates the operation.
$operation = new UserListOperation();
$operation->setCreate($userList);
// Issues a mutate request to add the user list and prints some information.
$userListServiceClient = $googleAdsClient->getUserListServiceClient();
$response = $userListServiceClient->mutateUserLists($customerId, [$operation]);
printf(
"Created combination user list with resource name '%s'.%s",
$response->getResults()[0]->getResourceName(),
PHP_EOL
);
}
Python
def main(client, customer_id, user_list_ids):
"""Creates a combination user list.
Args:
client: The Google Ads client.
customer_id: The customer ID for which to add the user list.
user_list_ids: A list of user list IDs to logically combine.
"""
# Get the UserListService client.
user_list_service = client.get_service("UserListService")
# Add each of the provided list IDs to a list of rule operands specifying
# which lists the operator should target.
logical_user_list_operand_info_list = []
for user_list_id in user_list_ids:
logical_user_list_operand_info = client.get_type(
"LogicalUserListOperandInfo"
)
logical_user_list_operand_info.user_list = user_list_service.user_list_path(
customer_id, user_list_id
)
logical_user_list_operand_info_list.append(
logical_user_list_operand_info
)
# Create a UserListOperation and populate the UserList.
user_list_operation = client.get_type("UserListOperation")
user_list = user_list_operation.create
user_list.name = f"My combination list of other user lists #{uuid4()}"
# Create a UserListLogicalRuleInfo specifying that a user should be added to
# the new list if they are present in any of the provided lists.
user_list_logical_rule_info = client.get_type("UserListLogicalRuleInfo")
# Using ANY means that a user should be added to the combined list if they
# are present on any of the lists targeted in the
# LogicalUserListOperandInfo. Use ALL to add users present on all of the
# provided lists or NONE to add users that aren't present on any of the
# targeted lists.
user_list_logical_rule_info.operator = (
client.enums.UserListLogicalRuleOperatorEnum.ANY
)
user_list_logical_rule_info.rule_operands.extend(
logical_user_list_operand_info_list
)
user_list.logical_user_list.rules.append(user_list_logical_rule_info)
# Issue a mutate request to add the user list, then print the results.
response = user_list_service.mutate_user_lists(
customer_id=customer_id, operations=[user_list_operation]
)
print(
"Created logical user list with resource name "
f"'{response.results[0].resource_name}.'"
)
Ruby
def add_logical_user_list(customer_id, user_list_ids)
# GoogleAdsClient will read a config file from
# ENV['HOME']/google_ads_config.rb when called without parameters
client = Google::Ads::GoogleAds::GoogleAdsClient.new
# Creates the UserListLogicalRuleInfo specifying that a user should be added
# to the new list if they are present in any of the provided lists.
user_list_logical_rule_info = client.resource.user_list_logical_rule_info do |info|
# Using ANY means that a user should be added to the combined list if they
# are present on any of the lists targeted in the logical_user_list_operand_info.
# Use ALL to add users present on all of the provided lists or NONE to add
# users that aren't present on any of the targeted lists.
info.operator = :ANY
user_list_ids.each do |list_id|
info.rule_operands << client.resource.logical_user_list_operand_info do |op|
op.user_list = client.path.user_list(customer_id, list_id)
end
end
end
# Creates the new combination user list operation.
operation = client.operation.create_resource.user_list do |ul|
ul.name = "My combination list of other user lists #{(Time.new.to_f * 1000).to_i}"
ul.logical_user_list = client.resource.logical_user_list_info do |info|
info.rules << user_list_logical_rule_info
end
end
# Issues a mutate request to add the user list and prints some information.
response = client.service.user_list.mutate_user_lists(
customer_id: customer_id,
operations: [operation],
)
puts "Created combination user list with resource name "\
"'#{response.results.first.resource_name}'"
end
Perl
sub add_logical_user_list {
my ($api_client, $customer_id, $user_list_ids) = @_;
# Add each of the provided list IDs to a list of rule operands specifying which
# lists the operator should target.
my $logical_user_list_operand_info_list = [];
foreach my $user_list_id (@$user_list_ids) {
push @$logical_user_list_operand_info_list,
Google::Ads::GoogleAds::V14::Common::LogicalUserListOperandInfo->new({
userList =>
Google::Ads::GoogleAds::V14::Utils::ResourceNames::user_list(
$customer_id, $user_list_id
)});
}
# Create the UserListLogicalRuleInfo specifying that a user should be added to
# the new list if they are present in any of the provided lists.
my $user_list_logical_rule_info =
Google::Ads::GoogleAds::V14::Common::UserListLogicalRuleInfo->new({
# Using ANY means that a user should be added to the combined list if they
# are present on any of the lists targeted in the LogicalUserListOperandInfo.
# Use ALL to add users present on all of the provided lists or NONE to add
# users that aren't present on any of the targeted lists.
operator => ANY,
ruleOperands => $logical_user_list_operand_info_list
});
# Create the new combination user list.
my $user_list = Google::Ads::GoogleAds::V14::Resources::UserList->new({
name => "My combination list of other user lists #" . uniqid(),
logicalUserList =>
Google::Ads::GoogleAds::V14::Common::LogicalUserListInfo->new({
rules => [$user_list_logical_rule_info]})});
# Create the operation.
my $user_list_operation =
Google::Ads::GoogleAds::V14::Services::UserListService::UserListOperation->
new({
create => $user_list
});
# Issue a mutate request to add the user list and print some information.
my $user_lists_response = $api_client->UserListService()->mutate({
customerId => $customer_id,
operations => [$user_list_operation]});
printf "Created combination user list with resource name '%s'.\n",
$user_lists_response->{results}[0]{resourceName};
return 1;
}