向 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的新转化。无需修改时间戳。请参阅转化调整简介。