此页面由 Cloud Translation API 翻译。

上传转化调整

将某次转化报告给 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());
      }
    }
  }
}UploadConversionAdjustment.java

C#

public void Run(GoogleAdsClient client, long customerId, long conversionActionId,
    string gclid, string conversionDateTime, string adjustmentDateTime,
    ConversionAdjustmentType adjustmentType,
    double? restatementValue)
{
    // Get the ConversionAdjustmentUploadService.
    ConversionAdjustmentUploadServiceClient conversionAdjustmentUploadService =
        client.GetService(Services.V16.ConversionAdjustmentUploadService);

    // Associate conversion adjustments with the existing conversion action.
    // The GCLID should have been uploaded before with a conversion.
    ConversionAdjustment conversionAdjustment = new ConversionAdjustment()
    {
        ConversionAction = ResourceNames.ConversionAction(customerId, conversionActionId),
        AdjustmentType = adjustmentType,
        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 },
                    PartialFailure = true,
                    ValidateOnly = false
                });

        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;
    }
}UploadConversionAdjustment.cs

PHP

public static function runExample(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    int $conversionActionId,
    string $gclid,
    string $adjustmentType,
    string $conversionDateTime,
    string $adjustmentDateTime,
    float $restatementValue
) {
    $conversionAdjustmentType = ConversionAdjustmentType::value($adjustmentType);

    // Associates conversion adjustments with the existing conversion action.
    // The GCLID should have been uploaded before with a conversion.
    $conversionAdjustment = new ConversionAdjustment([
        'conversion_action' =>
            ResourceNames::forConversionAction($customerId, $conversionActionId),
        'adjustment_type' => $conversionAdjustmentType,
        'gclid_date_time_pair' => new GclidDateTimePair([
            'gclid' => $gclid,
            'conversion_date_time' => $conversionDateTime
        ]),
        '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(
        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 Google Click ID '%s'.%s",
            $uploadedConversionAdjustment->getConversionAction(),
            $uploadedConversionAdjustment->getGclidDateTimePair()->getGclid(),
            PHP_EOL
        );
    }
}UploadConversionAdjustment.php

Python

def main(
    client,
    customer_id,
    conversion_action_id,
    gclid,
    adjustment_type,
    conversion_date_time,
    adjustment_date_time,
    restatement_value,
):
    conversion_adjustment_type_enum = client.enums.ConversionAdjustmentTypeEnum
    # Determine the adjustment type.
    conversion_adjustment_type = conversion_adjustment_type_enum[
        adjustment_type
    ].value

    # Associates conversion adjustments with the existing conversion action.
    # The GCLID should have been uploaded before with a 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

    # Set the Gclid Date
    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
        )

    conversion_adjustment_upload_service = client.get_service(
        "ConversionAdjustmentUploadService"
    )
    request = client.get_type("UploadConversionAdjustmentsRequest")
    request.customer_id = customer_id
    request.conversion_adjustments = [conversion_adjustment]
    request.partial_failure = True
    response = (
        conversion_adjustment_upload_service.upload_conversion_adjustments(
            request=request,
        )
    )
    conversion_adjustment_result = response.results[0]
    print(
        f"Uploaded conversion that occurred at "
        f'"{conversion_adjustment_result.adjustment_date_time}" '
        f"from Gclid "
        f'"{conversion_adjustment_result.gclid_date_time_pair.gclid}"'
        f' to "{conversion_adjustment_result.conversion_action}"'
    )upload_conversion_adjustment.py

Ruby

def upload_conversion_adjustment(
  customer_id,
  conversion_action_id,
  gclid,
  adjustment_type,
  conversion_date_time,
  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

  # Associate conversion adjustments with the existing conversion action.
  # The GCLID should have been uploaded before with a 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.gclid_date_time_pair = client.resource.gclid_date_time_pair do |gdtp|
      gdtp.gclid = gclid
      gdtp.conversion_date_time = conversion_date_time
    end
    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 at #{result.adjustment_date_time} " \
      "for adjustment #{result.adjustment_type} to #{result.conversion_action}."
    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|
        puts "\t#{error.error_code.error_code}: #{error.message}"
      end
    end
  end
endupload_conversion_adjustment.rb

Perl

sub upload_conversion_adjustment {
  my ($api_client, $customer_id, $conversion_action_id, $gclid,
    $adjustment_type, $conversion_date_time, $adjustment_date_time,
    $restatement_value)
    = @_;

  # Associate conversion adjustments with the existing conversion action.
  # The GCLID should have been uploaded before with a conversion.
  my $conversion_adjustment =
    Google::Ads::GoogleAds::V16::Services::ConversionAdjustmentUploadService::ConversionAdjustment
    ->new({
      conversionAction =>
        Google::Ads::GoogleAds::V16::Utils::ResourceNames::conversion_action(
        $customer_id, $conversion_action_id
        ),
      adjustmentType    => $adjustment_type,
      gclidDateTimePair =>
        Google::Ads::GoogleAds::V16::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::V16::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 Google Click ID '%s'.\n",
      $uploaded_conversion_adjustment->{conversionAction},
      $uploaded_conversion_adjustment->{gclidDateTimePair}{gclid};
  }

  return 1;
}upload_conversion_adjustment.pl

使用要求

在 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 错误：
- 系统从未报告此次转化。
- 系统在尝试调整之前不到 24 小时报告了转化。在某些情况下，这可能会导致 TOO_RECENT_CONVERSION 错误。
在以下任一条件下，您必须在 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 上传新的转化。时间戳无需修改。请参阅转化调整简介。

问题排查

转化价值规则