轉換已回報至 Google Ads 後，您可以在日後透過 Google Ads API 調整轉換。
如要調整轉換，您必須先設定轉換動作，並記錄要調整的轉換。
程式碼範例
Google Ads API 支援使用 order_id (也稱為交易 ID) 來識別要使用 ConversionAdjustmentUploadService 調整的轉換。
如要取得進行轉換調整所需的 conversion_action_id，請執行下列任一操作：
在 Google Ads 使用者介面中點選轉換詳細資料時，從網址中提供的
ctId參數取得值。查詢
conversion_action報表中的conversion_action.id的 Google Ads API。
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}'." )
小茹
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的新轉換。您不需要修改時間戳記。請參閱「關於轉換調整項」。