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 jak 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 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 informuje o jego typie, 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 element requestId, który jest unikalnym identyfikatorem żą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.v25.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 Wyjaśnienie błędów interfejsu API.

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
    );
    $errors = $googleAdsException->getGoogleAdsFailure()->getErrors();
    foreach ($errors 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 "
            f"'{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, wykonaj te instrukcje.

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 zarejestruj logi: zacznij od wyłapania wyjątków i opcjonalnego zarejestrowania logów interfejsu API.
2. Przeanalizuj 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 w określeniu, 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 uzyskać więcej informacji 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 swoim żądaniu.
6. Zapisz request_id: jeśli nie możesz rozwiązać problemu z błędem 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 uwzględnić request_id. Ten identyfikator pomaga inżynierom Google znaleźć szczegóły nieudanego żądania w logach serwera interfejsu Google Ads API i zbadać Twój problem.

Dalsze kroki

• Listę częstych problemów i ich rozwiązań znajdziesz w sekcji Typowe błędy.
• Bardziej zaawansowane techniki obsługi błędów, w tym logikę ponawiania i częściowe awarie, znajdziesz w artykule Informacje o błędach interfejsu API.