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ą sprawnie radzić sobie 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 postaci 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ć podstawową naturę 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 GoogleAdsFailure proto, który zawiera 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 konkretnym błędzie, który wystąpił.
• request_id: unikalny identyfikator żądania, przydatny do debugowania i wsparcia;

Każdy obiekt GoogleAdsError zawiera:

• errorCode: bardziej szczegółowy kod błędu specyficzny dla interfejsu Google Ads API, np. AuthenticationError.NOT_ADS_USER.
• message: czytelny opis konkretnego błędu.
• trigger: wartość, która spowodowała błąd (jeśli dotyczy).
• location: opisuje, w którym miejscu żądania wystąpił błąd, w tym ścieżki pól.
• details: dodatkowe szczegóły błędu, np. nieopublikowane przyczyny błędów.

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

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

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

W tym przykładzie pomimo informacji na najwyższym poziomie INVALID_ARGUMENT 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 strumieniowe, obiekt GoogleAdsFailure jest zwracany jako część metadanych końcowych w nagłówkach odpowiedzi gRPC. Jeśli używasz REST do standardowych wywołań, w odpowiedzi HTTP zwracana jest wartość GoogleAdsFailure. Biblioteki klienta zwykle zgłaszają to jako wyjątek z atrybutem GoogleAdsFailure.

Częściowe niepowodzenie

Jeśli używasz częściowego niepowodzenia, błędy dotyczące nieudanych operacji są zwracane w polu partial_failure_error odpowiedzi, a nie w nagłówkach odpowiedzi. W tym przypadku element GoogleAdsFailure jest osadzony w obiekcie google.rpc.Status w odpowiedzi.

Zadania wsadowe

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

Identyfikator żądania

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

request-id znajdziesz w kilku miejscach:

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

Podczas rejestrowania błędów lub kontaktowania się z zespołem pomocy pamiętaj, aby podać request-id, co 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 errorCode, message i location w ramach 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 żądaniu 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. Wdróż strategię 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żyj 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 odczekaj 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ń wycofywania, aby zapobiec problemowi „thundering herd”, w którym wielu klientów ponawia próbę jednocześnie.

4. Dokładnie rejestruj błędy: 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. Przekazywanie opinii użytkowników: na podstawie konkretnych kodów i wiadomości GoogleAdsError przekazuj użytkownikom aplikacji jasne i pomocne opinie. Na przykład zamiast „Wystąpił błąd” możesz podać „Wymagana jest nazwa kampanii” lub „Nie znaleziono podanego identyfikatora grupy reklam”.

Przestrzegając tych wytycznych, 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.