Błędy zostały podzielone na te ogólne kategorie:
- Uwierzytelnianie
- Możliwość ponownego wykonania
- Weryfikacja
- Powiązane z synchronizacją
Chociaż te kategorie nie obejmują wszystkich możliwych błędów, a niektóre z nich mogą pasować do więcej niż 1 kategorii, mogą one posłużyć jako punkt wyjścia do stworzenia struktury obsługi błędów w aplikacji. Więcej informacji o poszczególnych błędach znajdziesz w tych zasobach:
- Sekcja Typowe błędy zawiera więcej informacji o konkretnym błędzie.
- google.rpc.Status, aby uzyskać szczegółowe informacje o modelu błędu logicznego używanym przez interfejs API.
Błędy uwierzytelniania
Uwierzytelnianie polega na tym, czy użytkownik przyznał aplikacji uprawnienia do uzyskiwania dostępu do Google Ads w jego imieniu. Uwierzytelnianiem zarządza się za pomocą danych uwierzytelniających wygenerowanych w ramach przepływu danych OAuth 2.
Najczęstszą przyczyną błędu uwierzytelniania wynikającego z czynników niezależnych od Ciebie jest cofnięcie przez uwierzytelnionego użytkownika uprawnień do działania w jego imieniu, które zostały przyznane Twojej aplikacji. Jeśli np. Twoja aplikacja zarządza osobnymi kontami Google Ads dla niezależnych klientów i podczas zarządzania kontem danego klienta uwierzytelnia się jako każdy z nich, klient może w dowolnym momencie cofnąć dostęp aplikacji. W zależności od tego, kiedy dostęp został cofnięty, interfejs API może zwrócić bezpośrednio błąd AuthenticationError.OAUTH_TOKEN_REVOKED lub wbudowane obiekty danych logowania w bibliotekach klienta mogą wywołać wyjątek związany z anulowaniem tokenu. W obu przypadkach, jeśli aplikacja ma interfejs dla klientów, może poprosić ich o ponowne uruchomienie procesu OAuth 2 w celu przywrócenia uprawnień aplikacji do działania w imieniu klienta.
Błędy z możliwością ponownej próby
Niektóre błędy, takie jak TRANSIENT_ERROR lub INTERNAL_ERROR, mogą wskazywać na tymczasowy problem, który można rozwiązać, ponownie wysyłając żądanie po krótkiej przerwie.
W przypadku żądań inicjowanych przez użytkownika jedną z możliwych strategii jest natychmiastowe wskazanie błędu w interfejsie i danie użytkownikowi możliwości ponownego wykonania próby. Aplikacja może też najpierw automatycznie ponownie wysłać żądanie, wyświetlając błąd w interfejsie dopiero po osiągnięciu maksymalnej liczby prób lub po upływie łącznego czasu oczekiwania użytkownika.
W przypadku żądań inicjowanych na zapleczu aplikacja powinna automatycznie powtarzać żądanie do maksymalnej liczby prób.
Gdy powtarzasz próby wysyłania żądań, stosuj zasadę wzrastającego czasu do ponowienia. Jeśli na przykład wstrzymasz odtwarzanie 5 sekund przed pierwszą próbą, możesz wstrzymać je na 10 sekund po drugiej i na 20 sekund po trzeciej próbie. Wycofanie wykładnicze pomaga zadbać o to, aby nie wywoływać interfejsu API zbyt agresywnie.
Błędy weryfikacji
Błędy walidacji wskazują, że dane wejściowe operacji nie były akceptowalne.
Na przykład: PolicyViolationError, DateError, DateRangeError, StringLengthError i UrlFieldError.
Błędy weryfikacji występują najczęściej w przypadku żądań inicjowanych przez użytkownika, w których użytkownik wprowadził nieprawidłowy element wejściowy. W takich przypadkach należy wyświetlić użytkownikowi odpowiedni komunikat o błędzie, który zależy od otrzymanego błędu interfejsu API. Przed wywołaniem interfejsu API możesz też sprawdzić, czy dane wejściowe użytkownika nie zawierają typowych błędów. Dzięki temu aplikacja będzie szybciej reagować, a korzystanie z interfejsu API będzie bardziej efektywne. W przypadku żądań z back-endu aplikacja może dodać nieudaną operację do kolejki, aby operator mógł ją sprawdzić.
Błędy związane z synchronizacją
Wiele aplikacji Google Ads korzysta z lokalnej bazy danych do przechowywania obiektów Google Ads. Jednym z wyzwań związanych z tym podejściem jest to, że lokalna baza danych może stracić synchronizację z rzeczywistymi obiektami w Google Ads. Użytkownik może np. usunąć grupę reklam bezpośrednio w Google Ads, ale aplikacja i lokalna baza danych nie są świadome tej zmiany i nadal wysyłają wywołania interfejsu API tak, jakby grupa reklam nadal istniała. Te problemy z synchronizacją mogą objawiać się w postaci różnych błędów, takich jak DUPLICATE_CAMPAIGN_NAME, DUPLICATE_ADGROUP_NAME, AD_NOT_UNDER_ADGROUP, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD i wiele innych.
W przypadku żądań inicjowanych przez użytkownika jedną z możliwych strategii jest ostrzeżenie użytkownika o potencjalnym problemie z synchronizacją, natychmiastowe uruchomienie zadania, które pobiera odpowiednią klasę obiektów Google Ads i aktualizuje lokalną bazę danych, a następnie poproszenie użytkownika o odświeżenie interfejsu.
W przypadku żądań z tego poziomu niektóre błędy zawierają wystarczającą ilość informacji, aby aplikacja mogła automatycznie i stopniowo poprawiać lokalną bazę danych. Na przykład:CANNOT_OPERATE_ON_REMOVED_ADGROUPAD
powoduje, że aplikacja oznacza reklamę jako usunięta w lokalnej bazie danych. Błędy, których nie można obsłużyć w ten sposób, mogą spowodować uruchomienie przez aplikację bardziej kompleksowego zadania synchronizacji lub dodanie aplikacji do kolejki do sprawdzenia przez operatora.