请参阅本指南，了解客户名单更新、移除和报告。
使用 offlineUserDataJobService 更新列表
在创建客户名单并设置定位条件后，最好定期刷新这些名单。
如需使用最新数据更新列表，通常更高效的做法是附加或移除个别用户，而不是从列表中移除所有用户并从头开始上传。
附加到列表
若要附加到现有名单，请采用与创建新客户名单相同的方式创建 OfflineUserDataJob。
Java
private void addUsersToCustomerMatchUserList(
GoogleAdsClient googleAdsClient,
long customerId,
boolean runJob,
String userListResourceName,
Long offlineUserDataJobId,
ConsentStatus adPersonalizationConsent,
ConsentStatus adUserDataConsent)
throws UnsupportedEncodingException {
try (OfflineUserDataJobServiceClient offlineUserDataJobServiceClient =
googleAdsClient.getLatestVersion().createOfflineUserDataJobServiceClient()) {
String offlineUserDataJobResourceName;
if (offlineUserDataJobId == null) {
// Creates a new offline user data job.
OfflineUserDataJob.Builder offlineUserDataJobBuilder =
OfflineUserDataJob.newBuilder()
.setType(OfflineUserDataJobType.CUSTOMER_MATCH_USER_LIST)
.setCustomerMatchUserListMetadata(
CustomerMatchUserListMetadata.newBuilder().setUserList(userListResourceName));
// Adds consent information to the job if specified.
if (adPersonalizationConsent != null || adUserDataConsent != null) {
Consent.Builder consentBuilder = Consent.newBuilder();
if (adPersonalizationConsent != null) {
consentBuilder.setAdPersonalization(adPersonalizationConsent);
}
if (adUserDataConsent != null) {
consentBuilder.setAdUserData(adUserDataConsent);
}
// Specifies whether user consent was obtained for the data you are uploading. See
// https://www.google.com/about/company/user-consent-policy for details.
offlineUserDataJobBuilder
.getCustomerMatchUserListMetadataBuilder()
.setConsent(consentBuilder);
}
// Issues a request to create the offline user data job.
CreateOfflineUserDataJobResponse createOfflineUserDataJobResponse =
offlineUserDataJobServiceClient.createOfflineUserDataJob(
Long.toString(customerId), offlineUserDataJobBuilder.build());
offlineUserDataJobResourceName = createOfflineUserDataJobResponse.getResourceName();
System.out.printf(
"Created an offline user data job with resource name: %s.%n",
offlineUserDataJobResourceName);
} else {
// Reuses the specified offline user data job.
offlineUserDataJobResourceName =
ResourceNames.offlineUserDataJob(customerId, offlineUserDataJobId);
}
// Issues a request to add the operations to the offline user data job. This example
// only adds a few operations, so it only sends one AddOfflineUserDataJobOperations request.
// If your application is adding a large number of operations, split the operations into
// batches and send multiple AddOfflineUserDataJobOperations requests for the SAME job. See
// https://developers.google.com/google-ads/api/docs/remarketing/audience-types/customer-match#customer_match_considerations
// and https://developers.google.com/google-ads/api/docs/best-practices/quotas#user_data
// for more information on the per-request limits.
List<OfflineUserDataJobOperation> userDataJobOperations = buildOfflineUserDataJobOperations();
AddOfflineUserDataJobOperationsResponse response =
offlineUserDataJobServiceClient.addOfflineUserDataJobOperations(
AddOfflineUserDataJobOperationsRequest.newBuilder()
.setResourceName(offlineUserDataJobResourceName)
.setEnablePartialFailure(true)
.addAllOperations(userDataJobOperations)
.build());
// Prints the status message if any partial failure error is returned.
// NOTE: The details of each partial failure error are not printed here, you can refer to
// the example HandlePartialFailure.java to learn more.
if (response.hasPartialFailureError()) {
GoogleAdsFailure googleAdsFailure =
ErrorUtils.getInstance().getGoogleAdsFailure(response.getPartialFailureError());
System.out.printf(
"Encountered %d partial failure errors while adding %d operations to the offline user "
+ "data job: '%s'. Only the successfully added operations will be executed when "
+ "the job runs.%n",
googleAdsFailure.getErrorsCount(),
userDataJobOperations.size(),
response.getPartialFailureError().getMessage());
} else {
System.out.printf(
"Successfully added %d operations to the offline user data job.%n",
userDataJobOperations.size());
}
if (!runJob) {
System.out.printf(
"Not running offline user data job '%s', as requested.%n",
offlineUserDataJobResourceName);
return;
}
// Issues an asynchronous request to run the offline user data job for executing
// all added operations.
offlineUserDataJobServiceClient.runOfflineUserDataJobAsync(offlineUserDataJobResourceName);
// BEWARE! The above call returns an OperationFuture. The execution of that future depends on
// the thread pool which is owned by offlineUserDataJobServiceClient. If you use this future,
// you *must* keep the service client in scope too.
// See https://developers.google.com/google-ads/api/docs/client-libs/java/lro for more detail.
// Offline user data jobs may take 6 hours or more to complete, so instead of waiting for the
// job to complete, retrieves and displays the job status once. If the job is completed
// successfully, prints information about the user list. Otherwise, prints the query to use
// to check the job again later.
checkJobStatus(googleAdsClient, customerId, offlineUserDataJobResourceName);
}
}
C#
private static string AddUsersToCustomerMatchUserList(GoogleAdsClient client,
long customerId, string userListResourceName, bool runJob,
long? offlineUserDataJobId, ConsentStatus? adPersonalizationConsent,
ConsentStatus? adUserDataConsent)
{
// Get the OfflineUserDataJobService.
OfflineUserDataJobServiceClient service = client.GetService(
Services.V16.OfflineUserDataJobService);
string offlineUserDataJobResourceName;
if (offlineUserDataJobId == null)
{
// Creates a new offline user data job.
OfflineUserDataJob offlineUserDataJob = new OfflineUserDataJob()
{
Type = OfflineUserDataJobType.CustomerMatchUserList,
CustomerMatchUserListMetadata = new CustomerMatchUserListMetadata()
{
UserList = userListResourceName,
}
};
if (adUserDataConsent != null || adPersonalizationConsent != null)
{
// Specifies whether user consent was obtained for the data you are uploading.
// See https://www.google.com/about/company/user-consent-policy
// for details.
offlineUserDataJob.CustomerMatchUserListMetadata.Consent = new Consent();
if (adPersonalizationConsent != null)
{
offlineUserDataJob.CustomerMatchUserListMetadata.Consent.AdPersonalization =
(ConsentStatus)adPersonalizationConsent;
}
if (adUserDataConsent != null)
{
offlineUserDataJob.CustomerMatchUserListMetadata.Consent.AdUserData =
(ConsentStatus)adUserDataConsent;
}
}
// Issues a request to create the offline user data job.
CreateOfflineUserDataJobResponse response1 = service.CreateOfflineUserDataJob(
customerId.ToString(), offlineUserDataJob);
offlineUserDataJobResourceName = response1.ResourceName;
Console.WriteLine($"Created an offline user data job with resource name: " +
$"'{offlineUserDataJobResourceName}'.");
} else {
// Reuses the specified offline user data job.
offlineUserDataJobResourceName =
ResourceNames.OfflineUserDataJob(customerId, offlineUserDataJobId.Value);
}
AddOfflineUserDataJobOperationsRequest request =
new AddOfflineUserDataJobOperationsRequest()
{
ResourceName = offlineUserDataJobResourceName,
Operations = { BuildOfflineUserDataJobOperations() },
EnablePartialFailure = true,
};
// Issues a request to add the operations to the offline user data job. This example
// only adds a few operations, so it only sends one AddOfflineUserDataJobOperations
// request.
// If your application is adding a large number of operations, split the operations into
// batches and send multiple AddOfflineUserDataJobOperations requests for the SAME job.
// See https://developers.google.com/google-ads/api/docs/remarketing/audience-types/customer-match#customer_match_considerations
// and https://developers.google.com/google-ads/api/docs/best-practices/quotas#user_data
// for more information on the per-request limits.
AddOfflineUserDataJobOperationsResponse response2 =
service.AddOfflineUserDataJobOperations(request);
// Prints the status message if any partial failure error is returned.
// Note: The details of each partial failure error are not printed here,
// you can refer to the example HandlePartialFailure.cs to learn more.
if (response2.PartialFailureError != null)
{
// Extracts the partial failure from the response status.
GoogleAdsFailure partialFailure = response2.PartialFailure;
Console.WriteLine($"{partialFailure.Errors.Count} partial failure error(s) " +
$"occurred");
}
Console.WriteLine("The operations are added to the offline user data job.");
if (!runJob)
{
Console.WriteLine($"Not running offline user data job " +
"'{offlineUserDataJobResourceName}', as requested.");
return offlineUserDataJobResourceName;
}
// Issues an asynchronous request to run the offline user data job for executing
// all added operations.
Operation<Empty, OfflineUserDataJobMetadata> operationResponse =
service.RunOfflineUserDataJob(offlineUserDataJobResourceName);
Console.WriteLine("Asynchronous request to execute the added operations started.");
// Since offline user data jobs may take 24 hours or more to complete, it may not be
// practical to do operationResponse.PollUntilCompleted() to wait for the results.
// Instead, we save the offlineUserDataJobResourceName and use GoogleAdsService.Search
// to check for the job status periodically.
// In case you wish to follow the PollUntilCompleted or PollOnce approach, make sure
// you keep both operationResponse and service variables alive until the polling
// completes.
return offlineUserDataJobResourceName;
}
PHP
private static function addUsersToCustomerMatchUserList(
GoogleAdsClient $googleAdsClient,
int $customerId,
bool $runJob,
?string $userListResourceName,
?int $offlineUserDataJobId,
?int $adPersonalizationConsent,
?int $adUserDataConsent
) {
$offlineUserDataJobServiceClient =
$googleAdsClient->getOfflineUserDataJobServiceClient();
if (is_null($offlineUserDataJobId)) {
// Creates a new offline user data job.
$offlineUserDataJob = new OfflineUserDataJob([
'type' => OfflineUserDataJobType::CUSTOMER_MATCH_USER_LIST,
'customer_match_user_list_metadata' => new CustomerMatchUserListMetadata([
'user_list' => $userListResourceName
])
]);
// Adds consent information to the job if specified.
if (!empty($adPersonalizationConsent) || !empty($adUserDataConsent)) {
$consent = new Consent();
if (!empty($adPersonalizationConsent)) {
$consent->setAdPersonalization($adPersonalizationConsent);
}
if (!empty($adUserDataConsent)) {
$consent->setAdUserData($adUserDataConsent);
}
// Specifies whether user consent was obtained for the data you are uploading. See
// https://www.google.com/about/company/user-consent-policy for details.
$offlineUserDataJob->getCustomerMatchUserListMetadata()->setConsent($consent);
}
// Issues a request to create the offline user data job.
/** @var CreateOfflineUserDataJobResponse $createOfflineUserDataJobResponse */
$createOfflineUserDataJobResponse =
$offlineUserDataJobServiceClient->createOfflineUserDataJob(
CreateOfflineUserDataJobRequest::build($customerId, $offlineUserDataJob)
);
$offlineUserDataJobResourceName = $createOfflineUserDataJobResponse->getResourceName();
printf(
"Created an offline user data job with resource name: '%s'.%s",
$offlineUserDataJobResourceName,
PHP_EOL
);
} else {
// Reuses the specified offline user data job.
$offlineUserDataJobResourceName =
ResourceNames::forOfflineUserDataJob($customerId, $offlineUserDataJobId);
}
// Issues a request to add the operations to the offline user data job. This example
// only adds a few operations, so it only sends one AddOfflineUserDataJobOperations request.
// If your application is adding a large number of operations, split the operations into
// batches and send multiple AddOfflineUserDataJobOperations requests for the SAME job. See
// https://developers.google.com/google-ads/api/docs/remarketing/audience-types/customer-match#customer_match_considerations
// and https://developers.google.com/google-ads/api/docs/best-practices/quotas#user_data
// for more information on the per-request limits.
/** @var AddOfflineUserDataJobOperationsResponse $operationResponse */
$response = $offlineUserDataJobServiceClient->addOfflineUserDataJobOperations(
AddOfflineUserDataJobOperationsRequest::build(
$offlineUserDataJobResourceName,
self::buildOfflineUserDataJobOperations()
)->setEnablePartialFailure(true)
);
// Prints the status message if any partial failure error is returned.
// Note: The details of each partial failure error are not printed here, you can refer to
// the example HandlePartialFailure.php to learn more.
if ($response->hasPartialFailureError()) {
// Extracts the partial failure from the response status.
$partialFailure = GoogleAdsFailures::fromAny(
$response->getPartialFailureError()->getDetails()->getIterator()->current()
);
printf(
"%d partial failure error(s) occurred: %s.%s",
count($partialFailure->getErrors()),
$response->getPartialFailureError()->getMessage(),
PHP_EOL
);
} else {
print 'The operations are added to the offline user data job.' . PHP_EOL;
}
if ($runJob === false) {
printf(
"Not running offline user data job '%s', as requested.%s",
$offlineUserDataJobResourceName,
PHP_EOL
);
return;
}
// Issues an asynchronous request to run the offline user data job for executing all added
// operations. The result is OperationResponse. Visit the OperationResponse.php file for
// more details.
$offlineUserDataJobServiceClient->runOfflineUserDataJob(
RunOfflineUserDataJobRequest::build($offlineUserDataJobResourceName)
);
// Offline user data jobs may take 6 hours or more to complete, so instead of waiting
// for the job to complete, retrieves and displays the job status once. If the job is
// completed successfully, prints information about the user list. Otherwise, prints the
// query to use to check the job again later.
self::checkJobStatus($googleAdsClient, $customerId, $offlineUserDataJobResourceName);
}
Python
def add_users_to_customer_match_user_list(
client,
customer_id,
user_list_resource_name,
run_job,
offline_user_data_job_id,
ad_user_data_consent,
ad_personalization_consent,
):
"""Uses Customer Match to create and add users to a new user list.
Args:
client: The Google Ads client.
customer_id: The ID for the customer that owns the user list.
user_list_resource_name: The resource name of the user list to which to
add users.
run_job: If true, runs the OfflineUserDataJob after adding operations.
Otherwise, only adds operations to the job.
offline_user_data_job_id: ID of an existing OfflineUserDataJob in the
PENDING state. If None, a new job is created.
ad_user_data_consent: The consent status for ad user data for all
members in the job.
ad_personalization_consent: The personalization consent status for ad
user data for all members in the job.
"""
# Creates the OfflineUserDataJobService client.
offline_user_data_job_service_client = client.get_service(
"OfflineUserDataJobService"
)
if offline_user_data_job_id:
# Reuses the specified offline user data job.
offline_user_data_job_resource_name = (
offline_user_data_job_service_client.offline_user_data_job_path(
customer_id, offline_user_data_job_id
)
)
else:
# Creates a new offline user data job.
offline_user_data_job = client.get_type("OfflineUserDataJob")
offline_user_data_job.type_ = (
client.enums.OfflineUserDataJobTypeEnum.CUSTOMER_MATCH_USER_LIST
)
offline_user_data_job.customer_match_user_list_metadata.user_list = (
user_list_resource_name
)
# Specifies whether user consent was obtained for the data you are
# uploading. For more details, see:
# https://www.google.com/about/company/user-consent-policy
if ad_user_data_consent:
offline_user_data_job.customer_match_user_list_metadata.consent.ad_user_data = client.enums.ConsentStatusEnum[
ad_user_data_consent
]
if ad_personalization_consent:
offline_user_data_job.customer_match_user_list_metadata.consent.ad_personalization = client.enums.ConsentStatusEnum[
ad_personalization_consent
]
# Issues a request to create an offline user data job.
create_offline_user_data_job_response = (
offline_user_data_job_service_client.create_offline_user_data_job(
customer_id=customer_id, job=offline_user_data_job
)
)
offline_user_data_job_resource_name = (
create_offline_user_data_job_response.resource_name
)
print(
"Created an offline user data job with resource name: "
f"'{offline_user_data_job_resource_name}'."
)
# Issues a request to add the operations to the offline user data job.
# Best Practice: This example only adds a few operations, so it only sends
# one AddOfflineUserDataJobOperations request. If your application is adding
# a large number of operations, split the operations into batches and send
# multiple AddOfflineUserDataJobOperations requests for the SAME job. See
# https://developers.google.com/google-ads/api/docs/remarketing/audience-types/customer-match#customer_match_considerations
# and https://developers.google.com/google-ads/api/docs/best-practices/quotas#user_data
# for more information on the per-request limits.
request = client.get_type("AddOfflineUserDataJobOperationsRequest")
request.resource_name = offline_user_data_job_resource_name
request.operations = build_offline_user_data_job_operations(client)
request.enable_partial_failure = True
# Issues a request to add the operations to the offline user data job.
response = offline_user_data_job_service_client.add_offline_user_data_job_operations(
request=request
)
# Prints the status message if any partial failure error is returned.
# Note: the details of each partial failure error are not printed here.
# Refer to the error_handling/handle_partial_failure.py example to learn
# more.
# Extracts the partial failure from the response status.
partial_failure = getattr(response, "partial_failure_error", None)
if getattr(partial_failure, "code", None) != 0:
error_details = getattr(partial_failure, "details", [])
for error_detail in error_details:
failure_message = client.get_type("GoogleAdsFailure")
# Retrieve the class definition of the GoogleAdsFailure instance
# in order to use the "deserialize" class method to parse the
# error_detail string into a protobuf message object.
failure_object = type(failure_message).deserialize(
error_detail.value
)
for error in failure_object.errors:
print(
"A partial failure at index "
f"{error.location.field_path_elements[0].index} occurred.\n"
f"Error message: {error.message}\n"
f"Error code: {error.error_code}"
)
print("The operations are added to the offline user data job.")
if not run_job:
print(
"Not running offline user data job "
f"'{offline_user_data_job_resource_name}', as requested."
)
return
# Issues a request to run the offline user data job for executing all
# added operations.
offline_user_data_job_service_client.run_offline_user_data_job(
resource_name=offline_user_data_job_resource_name
)
# Retrieves and displays the job status.
check_job_status(client, customer_id, offline_user_data_job_resource_name)
Ruby
def add_users_to_customer_match_user_list(client, customer_id, run_job, user_list, job_id, ad_user_data_consent, ad_personalization_consent)
offline_user_data_service = client.service.offline_user_data_job
job_name = if job_id.nil?
# Creates the offline user data job.
offline_user_data_job = client.resource.offline_user_data_job do |job|
job.type = :CUSTOMER_MATCH_USER_LIST
job.customer_match_user_list_metadata =
client.resource.customer_match_user_list_metadata do |m|
m.user_list = user_list
if !ad_user_data_consent.nil? || !ad_personalization_consent.nil?
m.consent = client.resource.consent do |c|
# Specifies whether user consent was obtained for the data you are
# uploading. For more details, see:
# https://www.google.com/about/company/user-consent-policy
unless ad_user_data_consent.nil?
c.ad_user_data = ad_user_data_consent
end
unless ad_personalization_consent.nil?
c.ad_personalization = ad_personalization_consent
end
end
end
end
end
# Issues a request to create the offline user data job.
response = offline_user_data_service.create_offline_user_data_job(
customer_id: customer_id,
job: offline_user_data_job,
)
offline_user_data_job_resource_name = response.resource_name
puts "Created an offline user data job with resource name: " \
"#{offline_user_data_job_resource_name}"
offline_user_data_job_resource_name
else
client.path.offline_user_data_job(customer_id, job_id)
end
# Issues a request to add the operations to the offline user data job. This
# example only adds a few operations, so it only sends one
# AddOfflineUserDataJobOperations request. If your application is adding a
# large number of operations, split the operations into batches and send
# multiple AddOfflineUserDataJobOperations requests for the SAME job. See
# https://developers.google.com/google-ads/api/docs/remarketing/audience-types/customer-match#customer_match_considerations
# and https://developers.google.com/google-ads/api/docs/best-practices/quotas#user_data
# for more information on the per-request limits.
response = offline_user_data_service.add_offline_user_data_job_operations(
resource_name: offline_user_data_job_resource_name,
enable_partial_failure: true,
operations: build_offline_user_data_job_operations(client),
)
# Prints errors if any partial failure error is returned.
if response.partial_failure_error
failures = client.decode_partial_failure_error(response.partial_failure_error)
failures.each do |failure|
failure.errors.each do |error|
human_readable_error_path = error
.location
.field_path_elements
.map { |location_info|
if location_info.index
"#{location_info.field_name}[#{location_info.index}]"
else
"#{location_info.field_name}"
end
}.join(" > ")
errmsg = "error occured while adding operations " \
"#{human_readable_error_path}" \
" with value: #{error.trigger.string_value}" \
" because #{error.message.downcase}"
puts errmsg
end
end
end
puts "The operations are added to the offline user data job."
unless run_job
puts "Not running offline user data job #{job_name}, as requested."
return
end
# Issues an asynchronous request to run the offline user data job
# for executing all added operations.
response = offline_user_data_service.run_offline_user_data_job(
resource_name: offline_user_data_job_resource_name
)
puts "Asynchronous request to execute the added operations started."
puts "Waiting until operation completes."
# Offline user data jobs may take 6 hours or more to complete, so instead of
# waiting for the job to complete, retrieves and displays the job status
# once. If the job is completed successfully, prints information about the
# user list. Otherwise, prints the query to use to check the job again later.
check_job_status(
client,
customer_id,
offline_user_data_job_resource_name,
)
end
Perl
sub add_users_to_customer_match_user_list {
my ($api_client, $customer_id, $run_job, $user_list_resource_name,
$offline_user_data_job_id, $ad_personalization_consent,
$ad_user_data_consent)
= @_;
my $offline_user_data_job_service = $api_client->OfflineUserDataJobService();
my $offline_user_data_job_resource_name = undef;
if (!defined $offline_user_data_job_id) {
# Create a new offline user data job.
my $offline_user_data_job =
Google::Ads::GoogleAds::V16::Resources::OfflineUserDataJob->new({
type => CUSTOMER_MATCH_USER_LIST,
customerMatchUserListMetadata =>
Google::Ads::GoogleAds::V16::Common::CustomerMatchUserListMetadata->
new({
userList => $user_list_resource_name
})});
# Add consent information to the job if specified.
if ($ad_personalization_consent or $ad_user_data_consent) {
my $consent = Google::Ads::GoogleAds::V16::Common::Consent->new({});
if ($ad_personalization_consent) {
$consent->{adPersonalization} = $ad_personalization_consent;
}
if ($ad_user_data_consent) {
$consent->{adUserData} = $ad_user_data_consent;
}
# Specify whether user consent was obtained for the data you are uploading.
# See https://www.google.com/about/company/user-consent-policy for details.
$offline_user_data_job->{customerMatchUserListMetadata}{consent} =
$consent;
}
# Issue a request to create the offline user data job.
my $create_offline_user_data_job_response =
$offline_user_data_job_service->create({
customerId => $customer_id,
job => $offline_user_data_job
});
$offline_user_data_job_resource_name =
$create_offline_user_data_job_response->{resourceName};
printf
"Created an offline user data job with resource name: '%s'.\n",
$offline_user_data_job_resource_name;
} else {
# Reuse the specified offline user data job.
$offline_user_data_job_resource_name =
Google::Ads::GoogleAds::V16::Utils::ResourceNames::offline_user_data_job(
$customer_id, $offline_user_data_job_id);
}
# Issue a request to add the operations to the offline user data job.
# This example only adds a few operations, so it only sends one AddOfflineUserDataJobOperations
# request. If your application is adding a large number of operations, split
# the operations into batches and send multiple AddOfflineUserDataJobOperations
# requests for the SAME job. See
# https://developers.google.com/google-ads/api/docs/remarketing/audience-types/customer-match#customer_match_considerations
# and https://developers.google.com/google-ads/api/docs/best-practices/quotas#user_data
# for more information on the per-request limits.
my $user_data_job_operations = build_offline_user_data_job_operations();
my $response = $offline_user_data_job_service->add_operations(
{
resourceName => $offline_user_data_job_resource_name,
enablePartialFailure => "true",
operations => $user_data_job_operations
});
# Print the status message if any partial failure error is returned.
# Note: The details of each partial failure error are not printed here, you can
# refer to the example handle_partial_failure.pl to learn more.
if ($response->{partialFailureError}) {
# Extract the partial failure from the response status.
my $partial_failure = $response->{partialFailureError}{details}[0];
printf "Encountered %d partial failure errors while adding %d operations " .
"to the offline user data job: '%s'. Only the successfully added " .
"operations will be executed when the job runs.\n",
scalar @{$partial_failure->{errors}}, scalar @$user_data_job_operations,
$response->{partialFailureError}{message};
} else {
printf "Successfully added %d operations to the offline user data job.\n",
scalar @$user_data_job_operations;
}
if (!defined $run_job) {
print
"Not running offline user data job $offline_user_data_job_resource_name, as requested.\n";
return;
}
# Issue an asynchronous request to run the offline user data job for executing
# all added operations.
my $operation_response = $offline_user_data_job_service->run({
resourceName => $offline_user_data_job_resource_name
});
# Offline user data jobs may take 6 hours or more to complete, so instead of waiting
# for the job to complete, this example retrieves and displays the job status once.
# If the job is completed successfully, it prints information about the user list.
# Otherwise, it prints, the query to use to check the job status again later.
check_job_status($api_client, $customer_id,
$offline_user_data_job_resource_name);
}
使用标识符移除个别用户
如需移除个别用户，请执行以下操作：
在等于
UserData对象的OfflineUserDataJobOperation上设置remove属性。将一个或多个
UserIdentifier对象添加到user_identifiers[]重复字段。即使提交了多个与用户匹配的标识符，也只需使用一个用户标识符即可从列表中移除用户。
一次性从列表中移除所有数据
如需从列表中移除所有用户，请在 OfflineUserDataJobOperation 中将 remove_all 设置为 true，然后发出 RunOfflineUserDataJob 请求（其中包含与 remove_all 操作关联的资源名称）。
请注意，如果包含 remove_all 操作，该操作必须是作业中的第一个操作。否则，运行作业会返回 INVALID_OPERATION_ORDER 错误。如需将用户名单中的成员完全替换为新成员，请按以下顺序对 AddOfflineUserDataJobOperationsRequest 中的操作进行排序：
在
OfflineUserDataJobOperation中将remove_all设置为true。对于每个新成员，添加一个
create操作，在OfflineUserDataJobOperation中设置其UserData。
remove_all 操作每小时执行一次，最长可运行 24 小时。
客户名单刷新建议
您可以检索 REFRESH_CUSTOMER_MATCH_LIST 类型的建议，以识别一段时间内未更新的客户名单。如果您是第三方广告客户，并且允许用户管理客户名单，这种做法会特别有用。
如需详细了解如何使用建议，请参阅优化得分和建议指南。
移除列表
使用 UserListService.mutate_user_lists 方法，通过要移除的用户名单的资源名称提交 remove 操作。
使用 UserDataService 更新列表
UserDataService 的限制为每个请求 10 次操作和 100 次 user_identifiers，因此它更适合小规模更新。例如，如果每个 UserData 对象都有一个用于 hashed_email 的 UserIdentifier 和另一个用于 hashed_phone_number 的 UserIdentifier，则您的请求最多可以包含 50 个 UserData 对象。
UserDataService 包含 UploadUserData 方法，该方法接受 UploadUserDataRequest。除了 customer_id 之外，UploadUserDataRequest 还接受用于创建联系人的操作列表和名为 customer_match_user_list_metadata 的必填字段，该字段填充了要定位的再营销名单的资源名称。
首先创建一个用于填充 customer_id 和 customer_match_user_list_metadata 的 UploadUserDataRequest 实例：
Java
// Creates a request to add user data operations to the user list based on email addresses.
String userListResourceName = ResourceNames.userList(customerId, userListId);
UploadUserDataRequest.Builder uploadUserDataRequest =
UploadUserDataRequest.newBuilder()
.setCustomerId(String.valueOf(customerId))
.setCustomerMatchUserListMetadata(
CustomerMatchUserListMetadata.newBuilder()
.setUserList(StringValue.of(userListResourceName))
.build());
如需上传用户联系信息，请将 CrmBasedUserListInfo.upload_key_type 设置为 CONTACT_INFO。
首先，将操作添加到 UploadUserDataRequest 对象。每项操作都包含一个 create 字段，其中填充了 UserData 对象，这些对象包含一个或多个 UserIdentifier 实例。每个 UserIdentifier 都包含一条标识信息，也可以为多种不同的类型之一，下文将分别介绍每种类型。
如需上传客户电子邮件地址，请创建一个新的 UserDataOperation，并用 UserData 对象填充其 create 字段。UserData 对象接受 user_identifiers 列表。使用客户电子邮件地址填充 hashed_email 字段。
Java
ImmutableList<String> EMAILS =
ImmutableList.of("client1@example.com", "client2@example.com", " Client3@example.com ");
// Hash normalized email addresses based on SHA-256 hashing algorithm.
List<UserDataOperation> userDataOperations = new ArrayList<>(EMAILS.size());
for (String email : EMAILS) {
UserDataOperation userDataOperation =
UserDataOperation.newBuilder()
.setCreate(
UserData.newBuilder()
.addUserIdentifiers(
UserIdentifier.newBuilder()
.setHashedEmail(StringValue.of(toSHA256String(email)))
.build())
.build())
.build();
userDataOperations.add(userDataOperation);
}
uploadUserDataRequest.addAllOperations(userDataOperations);
上传用户 address_info 与上传用户电子邮件地址类似。
但是，请使用包含用户的 first_name、last_name、country_code 和 postal_code 的 OfflineUserAddressInfo 对象填充 address_info 字段，而不是传递 hashed_email。与电子邮件地址一样，first_name 和 last_name 也被视为个人身份信息，必须在上传之前进行哈希处理。
Java
String firstName = "Alex";
String lastName = "Quinn";
String countryCode = "US";
String postalCode = "94045";
UserIdentifier userIdentifierWithAddress =
UserIdentifier.newBuilder()
.setAddressInfo(
OfflineUserAddressInfo.newBuilder()
// First and last name must be normalized and hashed.
.setHashedFirstName(
StringValue.of(toSHA256String(firstName)))
.setHashedLastName(StringValue.of(toSHA256String(lastName)))
// Country code and zip code are sent in plaintext.
.setCountryCode(StringValue.of(countryCode))
.setPostalCode(StringValue.of(postalCode))
.build())
.build();
UserDataOperation userDataOperation =
UserDataOperation.newBuilder()
.setCreate(
UserData.newBuilder()
.addUserIdentifiers(userIdentifierWithAddress)
.build())
.build();
uploadUserDataRequest.addOperations(userDataOperation);
向 UploadUserDataRequest 实例添加操作后，对 UserDataServiceClient 调用 uploadUserData 方法，将请求发送到 Google Ads API 服务器。您可以通过获取响应对象中的操作计数和上传时间来查看请求是否成功。请注意，可能需要几个小时的时间才能对列表填充成员。
Java
// Creates the user data service client.
try (UserDataServiceClient userDataServiceClient =
googleAdsClient.getLatestVersion().createUserDataServiceClient()) {
// Add operations to the user list based on the user data type.
UploadUserDataResponse response =
userDataServiceClient.uploadUserData(uploadUserDataRequest.build());
// Displays the results.
// Reminder: it may take several hours for the list to be populated with members.
System.out.printf(
"Received %d operations at %s",
response.getReceivedOperationsCount().getValue(),
response.getUploadDateTime().getValue());
}
切换列表定位级别
如果您需要切换列表定位的级别（例如，从广告组级定位到广告系列级定位），请参阅“切换定位级别”指南。
查看名单效果
如需收集细分受众群的性能数据，请针对 ad_group_audience_view 或 campaign_audience_view 资源发出搜索请求。例如，您可以查看 conversions 或 cost_per_conversion 来确定定位细分受众群是否确实会促成更多转化，然后相应地调整出价调节系数。
SELECT
ad_group_criterion.criterion_id,
metrics.conversions,
metrics.cost_per_conversion
FROM ad_group_audience_view
我们建议您至少等待两周，然后再根据账号的流量优化出价。