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że to być np. podanie nieprawidłowego argumentu lub osiągnięcie limitu tworzenia nowych kampanii na koncie. W takich przypadkach interfejs API zwraca błąd, aby poinformować Cię o tym, 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ą 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ć GoogleAdsFailure obiekt. Ten obiekt zawiera listę poszczególnych GoogleAdsError obiektów, 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 typie 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 tego, która część żądania spowodowała błąd, np. nazwa konkretnego pola.

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

Przykład błędu

Oto przykład błędu w formacie JSON. Ten błąd oznacza, że w żądaniu brakuje pola name w ad_group o indeksie 0.

{
  "code": 3,
  "message": "Request contains an invalid argument.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v24.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 tej sekcji dowiesz się, 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 rejestrować logi

Aby rozwiązywać problemy z błędami, rejestruj logi błędów zwracane przez serwer interfejsu Google Ads API i sprawdzaj ich zawartość. Aby włączyć rejestrowanie i rejestrować logi 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 obsługiwać błędy

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

1. Przechwyć wyjątek i zarejestruj logi: zacznij od przechwycenia wyjątków i opcjonalnie zarejestrowania logów interfejsu API.
2. Sprawdź listę errors: przejrzyj każdy element GoogleAdsError w obiekcie GoogleAdsFailure. Wartości error_code i message informują o tym, co poszło nie tak.
3. Sprawdź wartość location: pole location może pomóc w ustaleniu, w którym miejscu żądania wystąpił problem.
4. Zapoznaj się z dokumentacją: w przypadku konkretnych kodów błędów sprawdź stronę z typowymi 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 zobaczysz REQUIRED_FIELD_MISSING, upewnij się, że w żądaniu podajesz to pole.
6. Zarejestruj request_id: jeśli nie możesz znaleźć sposobu na rozwiązanie problemu i musisz skontaktować się z zespołem pomocy), dołącz pełne logi żądania i odpowiedzi dotyczące nieudanego żądania. Pamiętaj, aby dołączyć the 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 artykule Typowe błędy.
• Więcej informacji o zaawansowanych technikach obsługi błędów, w tym o logice ponawiania i częściowych awariach, znajdziesz w artykule Informacje o błędach interfejsu API.