Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Как обрабатывать ошибки API

Запрос к Google Ads API может завершиться ошибкой по разным причинам. Например, вы могли указать недопустимый аргумент или в вашем аккаунте достигнуто ограничение на создание новых кампаний. В таких случаях API возвращает ошибку, чтобы вы знали, что пошло не так.

В этом руководстве рассказывается, как интерпретировать и обрабатывать ошибки API, чтобы создавать более надежные приложения.

Структура ошибки

Если вы используете одну из наших клиентских библиотек, ошибки API будут отображаться как исключения. Эти исключения содержат сведения, которые помогут вам понять, почему произошла ошибка.

Google Ads API возвращает информацию об ошибках в стандартном формате. Если произойдет ошибка, ответ будет содержать объект GoogleAdsFailure. Этот объект содержит список отдельных объектов GoogleAdsError, каждый из которых содержит подробные сведения об определенной ошибке.

Каждый объект GoogleAdsError содержит:

error_code – код ошибки, который указывает на ее тип, например AuthenticationError.NOT_ADS_USER.
message – человекочитаемое описание причины ошибки.
trigger – значение, которое вызвало ошибку, например "1234".
location – сведения о том, какая часть запроса вызвала ошибку, например название определенного поля.

Помимо списка ошибок, GoogleAdsFailure содержит requestId – уникальный идентификатор запроса к API, который привел к ошибке.

Пример ошибки

Ниже приведен пример ошибки в формате JSON. Эта ошибка означает, что в запросе отсутствует поле name объекта ad_group с индексом 0.

{
  "code": 3,
  "message": "Request contains an invalid argument.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v26.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "requestError": "REQUIRED_FIELD_MISSING"
          },
          "message": "Required field is missing",
          "location": {
            "fieldPathElements": [
              {
                "fieldName": "ad_group",
                "index": 0
              },
              {
                "fieldName": "name"
              }
            ]
          }
        }
      ],
      "requestId": "unique_request_id_12345"
    }
  ]
}

Подробнее об ошибках API…

Примеры клиентских библиотек

В следующем разделе показано, как обрабатывать ошибки в различных клиентских библиотеках.

Java

try {
  // Make an API call.
  ...
} catch (GoogleAdsException gae) {
  // GoogleAdsException is the base class for most exceptions thrown by an
  // API request. Instances of this exception have a message and a
  // GoogleAdsFailure that contains a collection of GoogleAdsErrors that
  // indicate the underlying causes of the GoogleAdsException.
  System.err.printf(
      "Request ID %s failed due to GoogleAdsException. Underlying"
          + " errors:%n",
      gae.getRequestId());
  int i = 0;
  for (GoogleAdsError googleAdsError :
      gae.getGoogleAdsFailure().getErrorsList()) {
    System.err.printf("  Error %d: %s%n", i++, googleAdsError);
  }
}

C#

try
{
    // Make an API call.
    ...
}
catch (GoogleAdsException e)
{
    Console.WriteLine($"Request with ID '{e.RequestId}' has failed.");
    Console.WriteLine("Google Ads failure details:");

    foreach (GoogleAdsError error in e.Failure.Errors)
    {
        Console.WriteLine($"{error.ErrorCode}: {error.Message}");
    }
}

PHP

try {
    // Make an API call.
    ...
} catch (GoogleAdsException $googleAdsException) {
    printf(
        "Request with ID '%s' has failed.%sGoogle Ads failure details:%s",
        $googleAdsException->getRequestId(),
        PHP_EOL,
        PHP_EOL
    );
    $errors = $googleAdsException->getGoogleAdsFailure()->getErrors();
    foreach ($errors as $error) {
        /** @var GoogleAdsError $error */
        printf(
            "\t%s: %s%s",
            $error->getErrorCode()->getErrorCode(),
            $error->getMessage(),
            PHP_EOL
        );
    }
}

Python

try:
    # Make an API call.
    ...
except GoogleAdsException as ex:
    print(
        f"Request with ID '{ex.request_id}' failed with status "
        f"'{ex.error.code().name}' and includes the following errors:"
    )
    for error in ex.failure.errors:
        print(
            f"\tError with message '{error.message}' and code "
            f"'{error.error_code}'."
        )

Ruby

begin
  # Make an API call.
  ...
rescue Google::Ads::GoogleAds::Errors::GoogleAdsError => e
  puts "API call failed with request ID: #{e.request_id}"
  e.failure.errors.each do |error|
    puts "\t#{error.error_code}: #{error.message}"
  end
end

Perl

# Try sending a mutate request to add the ad group ad.
...
if ($response->isa("Google::Ads::GoogleAds::GoogleAdsException")) {
  printf "Google Ads failure details:\n";
  foreach my $error (@{$response->get_google_ads_failure()->{errors}}) {
    printf "\t%s: %s\n",
      [keys %{$error->{errorCode}}]->[0], $error->{message};
  }
}

Как записать журналы

Чтобы устранить неполадки, соберите журналы ошибок, возвращенные сервером Google Ads API, и изучите их содержимое. Чтобы включить ведение журналов и записать журналы API, следуйте инструкциям ниже.

Java

Инструкции можно найти в руководстве по ведению журналов клиентской библиотеки Java.

C#

Чтобы инициализировать ведение журналов, добавьте следующую строку в метод Main перед выполнением вызовов API. Это гарантирует, что библиотека будет создавать журналы для всех вызовов API, выполненных вашим приложением.

using Google.Ads.GoogleAds.Util;
...

// Detailed logs.
TraceUtilities.Configure(TraceUtilities.DETAILED_REQUEST_LOGS_SOURCE,
    "/path/to/your/logs/details.log", System.Diagnostics.SourceLevels.All);

// Summary logs.
TraceUtilities.Configure(TraceUtilities.SUMMARY_REQUEST_LOGS_SOURCE,
    "/path/to/your/logs/summary.log", System.Diagnostics.SourceLevels.All);

Дополнительные варианты приведены в руководстве по ведению журналов в библиотеке.NET.

PHP

Вы можете задать конфигурацию ведения журнала в файле google_ads_php.ini клиентской библиотеки. Чтобы начать сбор подробных журналов ошибок, задайте для параметра logLevel значение NOTICE.

[LOGGING]
; Optional logging settings.
logFilePath = "path/to/your/file.log"
logLevel = "NOTICE"

Инструкции можно найти в руководстве по ведению журналов клиентской библиотеки PHP.

Python

Вы можете задать конфигурацию ведения журнала в файле google-ads.yaml клиентской библиотеки. Установите уровень ведения журнала DEBUG, чтобы начать сбор подробных журналов ошибок.

Дополнительные варианты приведены в руководстве по ведению журналов в библиотеке Python.

Ruby

Вы можете задать конфигурацию ведения журнала в файле google_ads_config.rb клиентской библиотеки. Установите уровень ведения журнала INFO, чтобы начать сбор подробных журналов ошибок.

Дополнительные варианты приведены в руководстве по ведению журналов в библиотеке Ruby.

Perl

Чтобы инициализировать ведение журнала, добавьте в скрипт Perl следующую строку перед вызовами API:

Google::Ads::GoogleAds::Logging::GoogleAdsLogger::enable_all_logging();

Дополнительные варианты приведены в руководстве по ведению журналов в библиотеке Perl.

curl

По умолчанию curl выводит ответы с ошибками в stderr.