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ć błędy interfejsu API i sobie z nimi radzić, aby tworzyć bardziej niezawodne aplikacje.

Struktura błędu

Jeśli używasz jednej z naszych bibliotek klienta, błędy interfejsu API są zgłaszane jako wyjątki. Te wyjątki zawierają szczegóły, które pomagają 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 określonym błędzie.

Każdy obiekt GoogleAdsError zawiera:

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

Oprócz listy błędów element GoogleAdsFailure zawiera requestId, czyli unikalny identyfikator żądania 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.v22.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 naszym przewodniku.

Przykłady bibliotek klienta

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

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

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

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
    );
    foreach ($googleAdsException->getGoogleAdsFailure()->getErrors() as $error) {
        /** @var GoogleAdsError $error */
        printf(
            "\t%s: %s%s",
            $error->getErrorCode()->getErrorCode(),
            $error->getMessage(),
            PHP_EOL
        );
    }
}

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 '{error.error_code}'.")

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

# 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 zwrócone przez serwer interfejsu Google Ads API i sprawdź ich zawartość. Aby włączyć logowanie i rejestrowanie logów interfejsu API, postępuj zgodnie z tymi instrukcjami.

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

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

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

Jak radzić sobie z błędami

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

1. Wyłap wyjątek i przechwyć dzienniki: zacznij od wyłapania wyjątków i opcjonalnego przechwycenia dzienników interfejsu API.
2. Sprawdź listę errors: przyjrzyj się każdemu elementowi GoogleAdsError w obiekcie GoogleAdsFailure. Komunikaty error_code i message poinformują Cię, co poszło nie tak.
3. Sprawdź wartość location: pole location może pomóc Ci określić, w którym miejscu żądania wystąpił problem.
4. Zapoznaj się z dokumentacją: w przypadku konkretnych kodów błędów sprawdź stronę z najczęstszymi błędami lub pełną listę kodów błędów, aby dowiedzieć się więcej o błędzie i sposobie jego naprawienia.
5. Dostosuj żądanie: na podstawie komunikatu o błędzie popraw żądanie do interfejsu API. 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 rozwiązać problemu i musisz skontaktować się z zespołem pomocy, dołącz pełne logi żądań i odpowiedzi dotyczące żądania, które się nie powiodło. Pamiętaj, aby dodać request_id. Ten identyfikator pomaga inżynierom Google znaleźć szczegóły nieudanego żądania w logach serwera Google Ads API i zbadać Twój problem.

Dalsze kroki

• Listę częstych problemów i sposobów ich rozwiązywania znajdziesz w sekcji Typowe błędy.
• Bardziej zaawansowane techniki obsługi błędów, w tym logikę ponawiania i częściowe niepowodzenie, znajdziesz w artykule Omówienie błędów interfejsu API.