向 Google Ads 报告转化后，您可以稍后在 Google Ads API 中调整转化。
若要调整转化，您必须先设置转化操作，同时必须已记录要调整的转化。
代码示例
Google Ads API 支持使用 order_id（也称为“交易 ID”）来标识要使用 ConversionAdjustmentUploadService 进行调整的转化。
如需获取进行转化调整所需的 conversion_action_id，您可以执行以下操作之一：
在 Google Ads 界面中点击转化详情时，从网址中提供的
ctId参数中获取值。在
conversion_action报告中，通过 Google Ads API 查询conversion_action.id。
Java
private void runExample(
GoogleAdsClient googleAdsClient,
long customerId,
long conversionActionId,
String orderId,
String adjustmentType,
String adjustmentDateTime,
@Nullable Float restatementValue)
throws InvalidProtocolBufferException {
// Gets the conversion adjustment enum value from the adjustmentType String.
ConversionAdjustmentType conversionAdjustmentType =
ConversionAdjustmentType.valueOf(adjustmentType);
// Applies the conversion adjustment to the existing conversion.
ConversionAdjustment conversionAdjustment =
ConversionAdjustment.newBuilder()
.setConversionAction(ResourceNames.conversionAction(customerId, conversionActionId))
.setAdjustmentType(conversionAdjustmentType)
// Sets the orderId to identify the conversion to adjust.
.setOrderId(orderId)
// As an alternative to setting orderId, you can provide a GclidDateTimePair, but
// setting orderId instead is strongly recommended.
// .setGclidDateTimePair(
// GclidDateTimePair.newBuilder()
// .setGclid(gclid)
// .setConversionDateTime(conversionDateTime)
// .build())
.setAdjustmentDateTime(adjustmentDateTime)
.build();
// Sets adjusted value for adjustment type RESTATEMENT.
if (restatementValue != null
&& conversionAdjustmentType == ConversionAdjustmentType.RESTATEMENT) {
conversionAdjustment =
conversionAdjustment.toBuilder()
.setRestatementValue(
RestatementValue.newBuilder().setAdjustedValue(restatementValue).build())
.build();
}
// Creates the conversion upload service client.
try (ConversionAdjustmentUploadServiceClient conversionUploadServiceClient =
googleAdsClient.getLatestVersion().createConversionAdjustmentUploadServiceClient()) {
// Uploads the click conversion. Partial failure should always be set to true.
UploadConversionAdjustmentsRequest request =
UploadConversionAdjustmentsRequest.newBuilder()
.setCustomerId(Long.toString(customerId))
// Enables partial failure (must be true).
.setPartialFailure(true)
.addConversionAdjustments(conversionAdjustment)
.build();
UploadConversionAdjustmentsResponse response =
conversionUploadServiceClient.uploadConversionAdjustments(request);
// Extracts the partial failure error if present on the response.
ErrorUtils errorUtils = ErrorUtils.getInstance();
GoogleAdsFailure googleAdsFailure =
response.hasPartialFailureError()
? errorUtils.getGoogleAdsFailure(response.getPartialFailureError())
: null;
// Constructs a protocol buffer printer that will print error details in a concise format.
final Printer errorPrinter = JsonFormat.printer().omittingInsignificantWhitespace();
// Prints the results for each adjustment, including any partial errors returned.
for (int opIndex = 0; opIndex < request.getConversionAdjustmentsCount(); opIndex++) {
ConversionAdjustmentResult result = response.getResults(opIndex);
if (errorUtils.isPartialFailureResult(result)) {
// The operation failed. Prints the error details.
for (GoogleAdsError googleAdsError :
errorUtils.getGoogleAdsErrors(opIndex, googleAdsFailure)) {
System.out.printf(
"%4d: Partial failure occurred: %s%n", opIndex, errorPrinter.print(googleAdsError));
}
} else {
System.out.printf(
"%4d: Uploaded conversion adjustment for conversion action '%s' and order ID '%s'.%n",
opIndex, result.getConversionAction(), result.getOrderId());
}
}
}
}
C#
public void Run(GoogleAdsClient client, long customerId, long conversionActionId,
string orderId, string adjustmentDateTime,
ConversionAdjustmentType adjustmentType,
double? restatementValue)
{
// Get the ConversionAdjustmentUploadService.
ConversionAdjustmentUploadServiceClient conversionAdjustmentUploadService =
client.GetService(Services.V18.ConversionAdjustmentUploadService);
// Associate conversion adjustments with the existing conversion action.
ConversionAdjustment conversionAdjustment = new ConversionAdjustment()
{
ConversionAction = ResourceNames.ConversionAction(customerId, conversionActionId),
AdjustmentType = adjustmentType,
// Sets the orderId to identify the conversion to adjust.
OrderId = orderId,
// As an alternative to setting orderId, you can provide a GclidDateTimePair,
// but setting orderId instead is strongly recommended.
//GclidDateTimePair = new GclidDateTimePair()
//{
// Gclid = gclid,
// ConversionDateTime = conversionDateTime,
//},
AdjustmentDateTime = adjustmentDateTime,
};
// Set adjusted value for adjustment type RESTATEMENT.
if (adjustmentType == ConversionAdjustmentType.Restatement)
{
conversionAdjustment.RestatementValue = new RestatementValue()
{
AdjustedValue = restatementValue.Value
};
}
try
{
// Issue a request to upload the conversion adjustment.
UploadConversionAdjustmentsResponse response =
conversionAdjustmentUploadService.UploadConversionAdjustments(
new UploadConversionAdjustmentsRequest()
{
CustomerId = customerId.ToString(),
ConversionAdjustments = { conversionAdjustment },
// Enables partial failure (must be true).
PartialFailure = true,
ValidateOnly = false
});
// Prints any partial errors returned.
// To review the overall health of your recent uploads, see:
// https://developers.google.com/google-ads/api/docs/conversions/upload-summaries
if (response.PartialFailureError != null)
{
// Extracts the partial failure from the response status.
GoogleAdsFailure partialFailure = response.PartialFailure;
Console.WriteLine($"{partialFailure.Errors.Count} partial failure error(s) " +
$"occurred");
}
else
{
ConversionAdjustmentResult result = response.Results[0];
// Print the result.
Console.WriteLine($"Uploaded conversion adjustment value of" +
$" '{result.ConversionAction}' for Google Click ID " +
$"'{result.GclidDateTimePair.Gclid}'");
}
}
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,
int $conversionActionId,
string $orderId,
string $adjustmentType,
string $adjustmentDateTime,
?float $restatementValue
) {
$conversionAdjustmentType = ConversionAdjustmentType::value($adjustmentType);
// Applies the conversion adjustment to the existing conversion.
$conversionAdjustment = new ConversionAdjustment([
'conversion_action' =>
ResourceNames::forConversionAction($customerId, $conversionActionId),
'adjustment_type' => $conversionAdjustmentType,
// Sets the orderId to identify the conversion to adjust.
'order_id' => $orderId,
// As an alternative to setting orderId, you can provide a 'gclid_date_time_pair', but
// setting 'order_id' instead is strongly recommended.
// 'conversion_date_time' must be in "yyyy-mm-dd hh:mm:ss+|-hh:mm" format.
/*
'gclid_date_time_pair' => new GclidDateTimePair([
'gclid' => 'INSERT_YOUR_GCLID_HERE',
'conversion_date_time' => 'INSERT_YOUR_CONVERSION_DATE_TIME_HERE'
]),
*/
'adjustment_date_time' => $adjustmentDateTime
]);
// Sets adjusted value for adjustment type RESTATEMENT.
if (
$restatementValue !== null
&& $conversionAdjustmentType === ConversionAdjustmentType::RESTATEMENT
) {
$conversionAdjustment->setRestatementValue(new RestatementValue([
'adjusted_value' => $restatementValue
]));
}
// Issues a request to upload the conversion adjustment.
$conversionAdjustmentUploadServiceClient =
$googleAdsClient->getConversionAdjustmentUploadServiceClient();
$response = $conversionAdjustmentUploadServiceClient->uploadConversionAdjustments(
// Enables partial failure (must be true).
UploadConversionAdjustmentsRequest::build($customerId, [$conversionAdjustment], 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()) {
printf(
"Partial failures occurred: '%s'.%s",
$response->getPartialFailureError()->getMessage(),
PHP_EOL
);
} else {
// Prints the result if exists.
/** @var ConversionAdjustmentResult $uploadedConversionAdjustment */
$uploadedConversionAdjustment = $response->getResults()[0];
printf(
"Uploaded conversion adjustment of '%s' for order ID '%s'.%s",
$uploadedConversionAdjustment->getConversionAction(),
$uploadedConversionAdjustment->getOrderId(),
PHP_EOL
);
}
}
Python
def main(
client,
customer_id,
conversion_action_id,
adjustment_type,
order_id,
adjustment_date_time,
restatement_value=None,
):
"""The main method that creates all necessary entities for the example.
Args:
client: an initialized GoogleAdsClient instance.
customer_id: a client customer ID.
conversion_action_id: the ID of the conversion action to upload the
adjustment to.
adjustment_type: the adjustment type, e.g. " "RETRACTION, RESTATEMENT.
order_id: the transaction ID of the conversion to adjust. Strongly
recommended instead of using gclid and conversion_date_time.
adjustment_date_time: the date and time of the adjustment.
restatement_value: the adjusted value for adjustment type RESTATEMENT.
"""
conversion_adjustment_type_enum = client.enums.ConversionAdjustmentTypeEnum
# Determine the adjustment type.
conversion_adjustment_type = conversion_adjustment_type_enum[
adjustment_type
].value
# Applies the conversion adjustment to the existing conversion.
conversion_adjustment = client.get_type("ConversionAdjustment")
conversion_action_service = client.get_service("ConversionActionService")
conversion_adjustment.conversion_action = (
conversion_action_service.conversion_action_path(
customer_id, conversion_action_id
)
)
conversion_adjustment.adjustment_type = conversion_adjustment_type
conversion_adjustment.adjustment_date_time = adjustment_date_time
# Sets the order_id to identify the conversion to adjust.
conversion_adjustment.order_id = order_id
# As an alternative to setting order_id, you can provide a
# gclid_date_time_pair, but setting order_id instead is strongly recommended.
# conversion_adjustment.gclid_date_time_pair.gclid = gclid
# conversion_adjustment.gclid_date_time_pair.conversion_date_time = (
# conversion_date_time
# )
# Sets adjusted value for adjustment type RESTATEMENT.
if (
restatement_value
and conversion_adjustment_type
== conversion_adjustment_type_enum.RESTATEMENT.value
):
conversion_adjustment.restatement_value.adjusted_value = float(
restatement_value
)
# Uploads the click conversion. Partial failure should always be set to
# true.
service = client.get_service("ConversionAdjustmentUploadService")
request = client.get_type("UploadConversionAdjustmentsRequest")
request.customer_id = customer_id
request.conversion_adjustments.append(conversion_adjustment)
# Enables partial failure (must be true)
request.partial_failure = True
response = service.upload_conversion_adjustments(request=request)
# Extracts the partial failure error if present on the response.
if response.partial_failure_error:
error_details = response.partial_failure_error.details
for i, conversion_adjustment_result in enumerate(response.results):
# If there's a GoogleAdsFailure in error_details at this position then
# the uploaded operation failed and we print the error message.
if error_details and error_details[i]:
error_detail = error_details[i]
failure_message = client.get_type("GoogleAdsFailure")
# Parse the string into a GoogleAdsFailure message instance.
# To access class-only methods on the message we retrieve its type.
GoogleAdsFailure = type(failure_message)
failure_object = GoogleAdsFailure.deserialize(error_detail.value)
for error in failure_object.errors:
# Construct and print a string that details which element in
# the operation list failed (by index number) as well as the
# error message and error code.
print(
"A partial failure at index "
f"{error.location.field_path_elements[0].index} occurred "
f"\nError message: {error.message}\nError code: "
f"{error.error_code}"
)
else:
print(
"Uploaded conversion adjustment for conversion action "
f"'{conversion_adjustment_result.conversion_action}' and order "
f"ID '{conversion_adjustment_result.order_id}'."
)
Ruby
def upload_conversion_adjustment(
customer_id,
conversion_action_id,
order_id,
adjustment_type,
adjustment_date_time,
restatement_value
)
# GoogleAdsClient will read a config file from
# ENV['HOME']/google_ads_config.rb when called without parameters
client = Google::Ads::GoogleAds::GoogleAdsClient.new
# Applies the conversion adjustment to the existing conversion.
conversion_adjustment = client.resource.conversion_adjustment do |ca|
ca.conversion_action = client.path.conversion_action(customer_id, conversion_action_id)
ca.adjustment_type = adjustment_type
ca.order_id = order_id
ca.adjustment_date_time = adjustment_date_time
# Set adjusted value for adjustment type RESTATEMENT.
if adjustment_type == :RESTATEMENT
ca.restatement_value = client.resource.restatement_value do |ra|
ra.adjusted_value = restatement_value.to_f
end
end
end
# Issue a request to upload the conversion adjustment(s).
response = client.service.conversion_adjustment_upload.upload_conversion_adjustments(
customer_id: customer_id,
# This example shows just one adjustment but you may upload multiple ones.
conversion_adjustments: [conversion_adjustment],
partial_failure: true
)
if response.partial_failure_error.nil?
# Process and print all results for multiple adjustments
response.results.each do |result|
puts "Uploaded conversion adjustment for conversion action #{result.conversion_action} "\
"and order ID #{result.order_id}."
end
else
# Print any partial errors returned.
failures = client.decode_partial_failure_error(response.partial_failure_error)
puts 'Request failed. Failure details:'
failures.each do |failure|
failure.errors.each do |error|
index = error.location.field_path_elements.first.index
puts "\toperation[#{index}] #{error.error_code.error_code}: #{error.message}"
end
end
end
end
Perl
sub upload_conversion_adjustment {
my ($api_client, $customer_id, $conversion_action_id, $order_id,
$adjustment_type, $adjustment_date_time, $restatement_value)
= @_;
# Applies the conversion adjustment to the existing conversion.
my $conversion_adjustment =
Google::Ads::GoogleAds::V18::Services::ConversionAdjustmentUploadService::ConversionAdjustment
->new({
conversionAction =>
Google::Ads::GoogleAds::V18::Utils::ResourceNames::conversion_action(
$customer_id, $conversion_action_id
),
adjustmentType => $adjustment_type,
# Sets the orderId to identify the conversion to adjust.
orderId => $order_id,
# As an alternative to setting orderId, you can provide a 'gclid_date_time_pair',
# but setting 'order_id' instead is strongly recommended.
# gclidDateTimePair =>
# Google::Ads::GoogleAds::V18::Services::ConversionAdjustmentUploadService::GclidDateTimePair
# ->new({
# gclid => $gclid,
# conversionDateTime => $conversion_date_time
# }
# ),
adjustmentDateTime => $adjustment_date_time,
});
# Set adjusted value for adjustment type RESTATEMENT.
$conversion_adjustment->{restatementValue} =
Google::Ads::GoogleAds::V18::Services::ConversionAdjustmentUploadService::RestatementValue
->new({
adjustedValue => $restatement_value
}) if defined $restatement_value && $adjustment_type eq RESTATEMENT;
# Issue a request to upload the conversion adjustment.
my $upload_conversion_adjustments_response =
$api_client->ConversionAdjustmentUploadService()
->upload_conversion_adjustments({
customerId => $customer_id,
conversionAdjustments => [$conversion_adjustment],
partialFailure => "true"
});
# Print any partial errors returned.
if ($upload_conversion_adjustments_response->{partialFailureError}) {
printf "Partial error encountered: '%s'.\n",
$upload_conversion_adjustments_response->{partialFailureError}{message};
}
# Print the result if valid.
my $uploaded_conversion_adjustment =
$upload_conversion_adjustments_response->{results}[0];
if (%$uploaded_conversion_adjustment) {
printf "Uploaded conversion adjustment of the conversion action " .
"with resource name '%s' for order ID '%s'.\n",
$uploaded_conversion_adjustment->{conversionAction},
$uploaded_conversion_adjustment->{orderId};
}
return 1;
}
要求
在 API 中调整转化时，请注意以下要求和限制：
只有管理转化操作的账号才能上传调整项。请参阅转化跟踪设置说明，确定哪个账号负责管理您的 Google Ads 账号的转化。
尝试使用其他账号上传调整项时，会导致
NO_CONVERSION_ACTION_FOUND错误。如果未启用调整项的转化操作，也会出现此错误。Google Ads 仅支持对类型为
SALESFORCE、UPLOAD_CLICKS或WEBPAGE的转化操作进行调整。如果尝试为转化操作不是上述类型的转化上传调整，则会导致INVALID_CONVERSION_ACTION_TYPE错误。用于指定日期和时间的字段需要时区，但时区不必与账号的时区相同。这些字段的格式为
yyyy-mm-dd HH:mm:ss+|-HH:mm，例如：2022-01-01 19:32:45-05:00（忽略夏令时）。创建转化操作后，请等待 4 到 6 小时，然后再调整其转化数据，以免出现
TOO_RECENT_CONVERSION_ACTION错误。如果转化从未上传，或者已上传但因被认定为无效或垃圾而被舍弃，则调整会失败并返回
CONVERSION_NOT_FOUND错误。在以下任一情况下，您都必须在
ConversionAdjustment中指定order_id：转化操作的
type等于WEBPAGE。您要调整的原始转化已分配
order_id。
如果您改为指定
gclid_date_time_pair，操作将分别失败并显示ConversionAdjustmentUploadError.MISSING_ORDER_ID_FOR_WEBPAGE或ConversionAdjustmentUploadError.CONVERSION_NOT_FOUND错误。创建
ConversionAdjustment时，UploadConversionAdjustmentsRequest的partial_failure属性应始终设置为true。同时处理有效和失败的操作时，请遵循部分失败准则。您无法通过调整来更改
ConversionAction。请改用RETRACTION移除之前的转化，然后上传包含更新后的ConversionAction的新转化。无需修改时间戳。请参阅转化调整简介。