Typy błędów

Błędy podzieliliśmy na te ogólne kategorie:

  • Uwierzytelnianie
  • Retryable
  • Weryfikacja
  • związane z synchronizacją,

Chociaż te kategorie nie obejmują wszystkich możliwych błędów, a niektóre mogą pasować do więcej niż jednej kategorii, mogą one stanowić punkt wyjścia do strukturyzacji obsługi błędów w aplikacji. Więcej informacji o poszczególnych błędach znajdziesz w tych materiałach:

  • Więcej informacji o konkretnym błędzie znajdziesz w sekcji Typowe błędy.
  • google.rpc.Status, aby dowiedzieć się więcej o modelu błędów logicznych używanym przez interfejs API.

Błędy uwierzytelniania

Uwierzytelnianie oznacza, czy użytkownik przyznał Twojej aplikacji uprawnienia do uzyskiwania dostępu do Google Ads w jego imieniu. Uwierzytelnianie jest zarządzane za pomocą danych logowania wygenerowanych przez przepływ OAuth2.

Najczęstszą przyczyną błędu uwierzytelniania wynikającą z czynników niezależnych od Ciebie jest cofnięcie przez uwierzytelnionego użytkownika uprawnień, które przyznał Twojej aplikacji do działania w jego imieniu. Jeśli na przykład Twoja aplikacja zarządza oddzielnymi kontami Google Ads niezależnych klientów i uwierzytelnia się oddzielnie jako każdy klient podczas zarządzania jego kontem, klient może w dowolnym momencie cofnąć dostęp do aplikacji. W zależności od tego, kiedy dostęp został cofnięty, interfejs API może bezpośrednio zwracać błąd AuthenticationError.OAUTH_TOKEN_REVOKED lub wbudowane obiekty danych logowania w bibliotekach klienta mogą zgłaszać wyjątek cofnięcia tokena. W obu przypadkach, jeśli Twoja aplikacja ma interfejs użytkownika dla klientów, może poprosić ich o ponowne uruchomienie procesu OAuth2, aby przywrócić uprawnienia aplikacji do działania w ich imieniu.

Błędy, które można ponowić

Niektóre błędy, np. TRANSIENT_ERROR lub INTERNAL_ERROR, mogą wskazywać na tymczasowy problem, który można rozwiązać, ponawiając próbę wysłania żądania po krótkiej przerwie.

W przypadku żądań zainicjowanych przez użytkownika jedną ze strategii jest natychmiastowe wskazanie błędu w interfejsie i udostępnienie użytkownikowi opcji ponowienia próby. Aplikacja może też najpierw automatycznie ponowić próbę wysłania żądania i wyświetlić błąd w interfejsie dopiero po osiągnięciu maksymalnej liczby ponownych prób lub łącznego czasu oczekiwania użytkownika.

W przypadku żądań zainicjowanych na serwerze aplikacja powinna automatycznie ponawiać żądanie maksymalną liczbę razy.

Podczas ponawiania żądań stosuj zasadę wzrastającego czasu do ponowienia. Jeśli na przykład przed pierwszą próbą ponowienia wstrzymasz działanie na 5 sekund, po drugiej próbie możesz wstrzymać je na 10 sekund, a po trzeciej na 20 sekund. Wycofywanie wykładnicze pomaga uniknąć zbyt częstego wywoływania interfejsu API.

Błędy weryfikacji

Błędy weryfikacji wskazują, że dane wejściowe operacji były nieprawidłowe. Na przykład PolicyViolationError, DateError, DateRangeError, StringLengthError i UrlFieldError.

Błędy weryfikacji występują najczęściej w przypadku żądań zainicjowanych przez użytkownika, w których podał on nieprawidłowe dane wejściowe. W takich przypadkach należy wyświetlić użytkownikowi odpowiedni komunikat o błędzie na podstawie otrzymanego błędu interfejsu API. Możesz też sprawdzać dane wejściowe użytkownika pod kątem typowych błędów przed wywołaniem interfejsu API, co zwiększy szybkość reakcji aplikacji i efektywność korzystania z interfejsu API. W przypadku żądań z backendu aplikacja może dodać nieudaną operację do kolejki, aby operator mógł ją sprawdzić.

Wiele aplikacji Google Ads ma lokalną bazę danych, w której przechowuje obiekty Google Ads. Jednym z wyzwań związanych z tym podejściem jest to, że lokalna baza danych może utracić synchronizację z rzeczywistymi obiektami w Google Ads. Użytkownik może na przykład usunąć grupę reklam bezpośrednio w Google Ads, ale aplikacja i lokalna baza danych nie będą miały świadomości tej zmiany i nadal będą wysyłać wywołania interfejsu API tak, jakby grupa reklam istniała. Problemy z synchronizacją mogą się objawiać różnymi błędami, takimi jak DUPLICATE_CAMPAIGN_NAME, DUPLICATE_ADGROUP_NAME, AD_NOT_UNDER_ADGROUP, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD i wieloma innymi.

W przypadku żądań inicjowanych przez użytkownika jedną ze strategii jest powiadomienie użytkownika o możliwym problemie z synchronizacją, natychmiastowe uruchomienie zadania, które pobiera odpowiednią klasę obiektów Google Ads i aktualizuje lokalną bazę danych, a następnie wyświetlenie użytkownikowi prośby o odświeżenie interfejsu.

W przypadku żądań backendu niektóre błędy zawierają wystarczająco dużo informacji, aby aplikacja mogła automatycznie i stopniowo poprawiać lokalną bazę danych. Na przykład CANNOT_OPERATE_ON_REMOVED_ADGROUPAD powinno spowodować oznaczenie tej reklamy w aplikacji jako usuniętej w lokalnej bazie danych. Błędy, których nie można rozwiązać w ten sposób, mogą spowodować uruchomienie przez aplikację pełniejszego zadania synchronizacji lub dodanie jej do kolejki do sprawdzenia przez operatora.

Dalej
Typowe błędy