Informacje o błędach interfejsu API

Z tego przewodnika dowiesz się, jak interfejs Google Ads API obsługuje błędy i jak o nich informuje. Zrozumienie struktury i znaczenia błędów interfejsu API jest kluczowe do tworzenia niezawodnych aplikacji, które mogą sobie poradzić z problemami, od nieprawidłowych danych wejściowych po tymczasową niedostępność usługi.

Interfejs Google Ads API jest zgodny ze standardowym modelem błędów interfejsów API Google, który jest oparty na kodach stanu gRPC. Każda odpowiedź interfejsu API, która powoduje błąd, zawiera obiekt Status, który zawiera:

• Kod błędu w formie liczby.
• komunikat o błędzie,
• Opcjonalne dodatkowe szczegóły błędu.

Kody błędów kanonicznych

Interfejs Google Ads API używa zestawu kanonicznych kodów błędów zdefiniowanych przez gRPC i HTTP. Te kody zawierają ogólne informacje o rodzaju błędu. Zawsze najpierw sprawdzaj ten kod numeryczny, aby zrozumieć podstawowy charakter problemu.

W tabeli poniżej znajdziesz podsumowanie najczęstszych kodów, które możesz napotkać podczas korzystania z interfejsu Google Ads API:

Więcej informacji o tych kodach znajdziesz w przewodniku API Design Guide – kody błędów.

Szczegóły błędu

Oprócz kodu najwyższego poziomu interfejs Google Ads API udostępnia bardziej szczegółowe informacje o błędach w polu details obiektu Status. To pole często zawiera protokół GoogleAdsFailure, który obejmuje listę poszczególnych obiektów GoogleAdsError.

Każdy obiekt GoogleAdsFailure zawiera:

• errors: lista obiektów GoogleAdsError, z których każdy zawiera szczegółowe informacje o wystąpieniu konkretnego błędu.
• request_id: unikalny identyfikator żądania, przydatny do debugowania i wsparcia.

Każdy obiekt GoogleAdsError zawiera:

• error_code: bardziej szczegółowe, dotyczące interfejsu Google Ads APIErrorCode (częste błędy), np.AuthenticationError.NOT_ADS_USER.
• message: opis konkretnego błędu w formie zrozumiałej dla człowieka.
• trigger: Value, który spowodował błąd (w odpowiednich przypadkach).
• location: ErrorLocation opisujący, w którym miejscu żądania wystąpił błąd, w tym ścieżki pól.
• details: dodatkowe ErrorDetails, np. nieopublikowane przyczyny błędów.

Przykład szczegółów błędu

Gdy wystąpi błąd, biblioteka klienta umożliwi Ci dostęp do tych szczegółów. Na przykład INVALID_ARGUMENT (kod 3) może mieć takie szczegóły:GoogleAdsFailure

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v25.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 0 },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 0 },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ],
      "requestId": "AbCdEfGhIjKlMnOpQrStUv"
    }
  ]
}

W tym przykładzie pomimo informacji INVALID_ARGUMENT na najwyższym poziomie szczegóły GoogleAdsFailure wskazują, że problem spowodowały pola name i description oraz dlaczego (REQUIRED i TOO_SHORT).

Znajdź szczegóły błędu

Sposób uzyskiwania dostępu do szczegółów błędu zależy od tego, czy używasz standardowych wywołań interfejsu API, częściowego niepowodzenia czy przesyłania strumieniowego.

Standardowe i strumieniowe wywołania interfejsu API

Gdy wywołanie interfejsu API zakończy się niepowodzeniem bez użycia częściowego niepowodzenia, w tym wywołania przesyłania strumieniowego, obiekt GoogleAdsFailure jest zwracany jako część metadanych końcowych w nagłówkach odpowiedzi gRPC. Jeśli używasz interfejsu REST do standardowych połączeń, w odpowiedzi HTTP zwracany jest kod GoogleAdsFailure. Biblioteki klienta zwykle zgłaszają to jako wyjątek z atrybutem GoogleAdsFailure.

Częściowe niepowodzenie

Jeśli używasz częściowej awarii, błędy dotyczące nieudanych operacji są zwracane w polu partial_failure_error odpowiedzi, a nie w nagłówkach odpowiedzi. W tym przypadku obiekt GoogleAdsFailure jest zagnieżdżony w obiekcie google.rpc.Status w odpowiedzi.

Zadania wsadowe

W przypadku przetwarzania wsadowego błędy poszczególnych operacji można znaleźć, wywołując BatchJobService.ListBatchJobResults po zakończeniu zadania. Każdy wynik operacji będzie zawierać pole status z informacjami o błędach, jeśli operacja się nie powiodła.

Identyfikator żądania

request-id to unikalny ciąg znaków, który identyfikuje Twoje żądanie do interfejsu API i jest niezbędny do rozwiązywania problemów.

request-id znajdziesz w kilku miejscach:

• GoogleAdsFailure: jeśli wywołanie interfejsu API nie powiedzie się i zostanie zwrócony kod GoogleAdsFailure, będzie on zawierać kod request_id.
• Metadane końcowe: w przypadku żądań zakończonych powodzeniem i niepowodzeniem w metadanych końcowych odpowiedzi gRPC dostępny jest element request-id.
• Nagłówki odpowiedzi: w przypadku żądań zakończonych powodzeniem i niepowodzeniem wartość request-id jest też dostępna w nagłówkach odpowiedzi gRPC i HTTP, z wyjątkiem żądań przesyłania strumieniowego zakończonych powodzeniem.
• SearchGoogleAdsStreamResponse: W przypadku żądań przesyłania strumieniowego każda wiadomość SearchGoogleAdsStreamResponse zawiera pole request_id.

Podczas zgłaszania błędów lub kontaktowania się z zespołem pomocy pamiętaj, aby dołączyć znak request-id, który ułatwi diagnozowanie problemów.

Sprawdzone metody obsługi błędów

Aby tworzyć odporne aplikacje, stosuj te sprawdzone metody:

1. Sprawdź szczegóły błędu: zawsze analizuj pole details obiektu Status, zwracając szczególną uwagę na GoogleAdsFailure. Szczegółowe informacje error_code, message i location w GoogleAdsError dostarczają najbardziej przydatnych informacji do debugowania i opinii użytkowników.

2. Odróżniaj błędy klienta od błędów serwera:

   • Błędy klienta: kody takie jak INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. Wymagają one zmian w prośbie lub w stanie/danych logowania aplikacji. Nie ponawiaj żądania bez rozwiązania problemu.
   • Błędy serwera: kody takie jak UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN. Wskazują one na tymczasowy problem z usługą API.

3. Wdrożenie strategii ponawiania:

   • Kiedy ponawiać próbę: ponawiaj próbę tylko w przypadku przejściowych błędów serwera, takich jak UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN i ABORTED.
   • Wzrastający czas do ponowienia: używaj algorytmu wzrastającego czasu do ponowienia, aby czekać coraz dłużej między ponownymi próbami. Pomaga to uniknąć przeciążenia już i tak obciążonej usługi. Na przykład poczekaj 1 sekundę, potem 2 sekundy, a następnie 4 sekundy, aż do osiągnięcia maksymalnej liczby ponownych prób lub łącznego czasu oczekiwania.
   • Jitter: dodaj niewielką losową wartość „jitter” do opóźnień czasu do ponowienia, aby zapobiec problemowi „thundering herd”, w którym wielu klientów ponawia próbę jednocześnie.

4. Dokładne rejestrowanie: rejestruj pełną odpowiedź o błędzie, w tym wszystkie szczegóły, a zwłaszcza identyfikator żądania. Te informacje są niezbędne do debugowania i zgłaszania problemów zespołowi pomocy Google.

5. Przekazuj użytkownikom informacje zwrotne: na podstawie konkretnych kodów i wiadomości GoogleAdsError przekazuj użytkownikom aplikacji jasne i pomocne informacje zwrotne. Na przykład zamiast po prostu „Wystąpił błąd” możesz napisać „Wymagana jest nazwa kampanii” lub „Nie znaleziono podanego identyfikatora grupy reklam”.

Postępując zgodnie z tymi wytycznymi, możesz skutecznie diagnozować i obsługiwać błędy zwracane przez interfejs Google Ads API, co pozwoli Ci tworzyć bardziej stabilne i przyjazne dla użytkownika aplikacje.