Obsługa błędów interfejsu API

Gdy wysyłasz żądanie do interfejsu Google Ads API, może ono zostać niezrealizowane z różnych powodów. Możesz na przykład podać nieprawidłowy argument lub Twoje konto mogło osiągnąć limit tworzenia nowych kampanii. W takich przypadkach interfejs API zwraca błąd, aby poinformować Cię, co poszło nie tak.

Z tego przewodnika dowiesz się, jak odczytywać i obsługiwać błędy interfejsu API, aby tworzyć bardziej niezawodne aplikacje.

Struktura błędu

Jeśli używasz jednej z naszych bibliotek klienta, błędy interfejsu API są wyświetlane jako wyjątki. Te wyjątki zawierają szczegółowe informacje, które pomogą Ci zrozumieć, dlaczego wystąpił błąd.

Interfejs Google Ads API zwraca informacje o błędach w standardowym formacie. Jeśli wystąpi błąd, odpowiedź będzie zawierać obiekt GoogleAdsFailure. Ten obiekt zawiera listę poszczególnych obiektów GoogleAdsError, z których każdy zawiera szczegółowe informacje o konkretnym błędzie.

Każdy obiekt GoogleAdsError zawiera:

  • error_code: konkretny kod błędu, który wskazuje typ błędu, np. AuthenticationError.NOT_ADS_USER.
  • message: zrozumiały dla człowieka opis przyczyny błędu.
  • trigger: wartość, która spowodowała błąd, np. „1234”.
  • location: szczegóły dotyczące tego, która część żądania spowodowała błąd, np. nazwa konkretnego pola.

Oprócz listy błędów GoogleAdsFailure zawiera też requestId, czyli unikalny identyfikator żądania do interfejsu API, które spowodowało błąd.

Przykładowy błąd

Oto przykład błędu w formacie JSON. Ten błąd oznacza, że w żądaniu brakuje pola name elementu ad_group o indeksie 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"
    }
  ]
}

Więcej informacji o błędach interfejsu API znajdziesz w artykule Informacje o błędach interfejsu API.

Przykłady bibliotek klienta

W sekcji poniżej pokazujemy, jak obsługiwać błędy w różnych bibliotekach klienta.

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};
  }
}

Jak przechwytywać dzienniki

Aby rozwiązać problemy, przechwyć dzienniki błędów zwracane przez serwer interfejsu Google Ads API i sprawdź ich zawartość. Aby włączyć logowanie i przechwytywać logi interfejsu API, postępuj zgodnie z tymi instrukcjami.

Java

Instrukcje znajdziesz w przewodniku po logowaniu w bibliotece klienta Java.

C#

Możesz zainicjować logowanie, dodając ten wiersz w metodzie Main przed wykonaniem jakichkolwiek wywołań interfejsu API. Dzięki temu biblioteka będzie generować logi dla wszystkich wywołań interfejsu API wykonywanych przez aplikację.

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);

Więcej opcji znajdziesz w przewodniku po logowaniu w bibliotece .NET.

PHP

Konfigurację logowania możesz ustawić w pliku google_ads_php.ini biblioteki klienta. Ustaw logLevel na NOTICE, aby rozpocząć rejestrowanie szczegółowych dzienników błędów.

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

Instrukcje znajdziesz w przewodniku po logowaniu w bibliotece klienta PHP.

Python

Konfigurację logowania możesz ustawić w pliku google-ads.yaml biblioteki klienta. Ustaw poziom rejestrowania na DEBUG, aby rozpocząć rejestrowanie szczegółowych dzienników błędów.

Więcej opcji znajdziesz w przewodniku po logowaniu w bibliotece Pythona.

Ruby

Konfigurację logowania możesz ustawić w pliku google_ads_config.rb biblioteki klienta. Ustaw poziom rejestrowania na INFO, aby rozpocząć rejestrowanie szczegółowych dzienników błędów.

Więcej opcji znajdziesz w przewodniku po logowaniu w bibliotece Ruby.

Perl

Aby zainicjować logowanie, dodaj ten wiersz w skrypcie Perl przed wywołaniem interfejsu API.

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

Więcej opcji znajdziesz w przewodniku po logowaniu w bibliotece Perl.

curl

curl domyślnie drukuje nieudane odpowiedzi do stderr.

Jak postępować w przypadku błędów

Jeśli wystąpi błąd, wykonaj te czynności:

  1. Przechwytywanie wyjątków i logów: zacznij od przechwytywania wyjątków i opcjonalnie logów interfejsu API.
  2. Sprawdź listę errors: przyjrzyj się każdemu elementowi GoogleAdsError w obiekcie GoogleAdsFailure. error_code i message poinformują Cię, co poszło nie tak.
  3. Sprawdź wartość location: pole location może pomóc Ci określić, gdzie w żądaniu wystąpił problem.
  4. Zapoznaj się z dokumentacją: aby uzyskać więcej informacji o konkretnych kodach błędów i sposobach ich naprawienia, odwiedź stronę z typowymi błędami lub zapoznaj się z pełną dokumentacją kodów błędów.
  5. Dostosuj żądanie: popraw żądanie do interfejsu API na podstawie komunikatu o błędzie. Jeśli na przykład widzisz REQUIRED_FIELD_MISSING, upewnij się, że podajesz to pole w żądaniu.
  6. Zapisz request_id: jeśli nie możesz znaleźć rozwiązania błędu i musisz skontaktować się z zespołem pomocy, dołącz pełne dzienniki żądań i odpowiedzi dotyczące nieudanego żądania. Pamiętaj, aby uwzględnić request_id. Ten identyfikator pomaga inżynierom Google znaleźć szczegóły nieudanego żądania w logach serwera interfejsu Google Ads API i zbadać problem.

Dalsze kroki

  • Listę częstych problemów i ich rozwiązań znajdziesz w sekcji Typowe błędy.
  • Więcej informacji o bardziej zaawansowanych technikach obsługi błędów, w tym o logice ponawiania prób i częściowych niepowodzeniach, znajdziesz w artykule Informacje o błędach interfejsu API.
Wstecz
Krótkie wprowadzenie
Dalej
Typowe błędy