Aby zapewnić użytkownikom wygodę, kod powinien prawidłowo obsługiwać błędy. Wyświetlaj użytkownikom komunikaty o błędach, które zawierają informacje o krokach, jakie należy podjąć, aby rozwiązać problem.
W tym dokumencie opisujemy błędy, które mogą wystąpić w przypadku łączników, jak działają komunikaty o błędach i jak prawidłowo obsługiwać błędy łączników.
Informacja: więcej informacji o obsłudze wyjątków w JavaScript znajdziesz w artykule Instrukcja try...catch.
Rodzaje błędów
Rodzaje i przyczyny błędów, które mogą wystąpić podczas korzystania z Twojego złącza, zwykle należą do jednej z tych 3 kategorii:
Błędy wewnętrzne i zewnętrzne oprogramowania sprzęgającego powinny być obsługiwane przez dewelopera oprogramowania sprzęgającego. Te błędy występują z powodu kodu napisanego przez dewelopera.
Wewnętrzny błąd oprogramowania sprzęgającego
Wewnętrzne błędy oprogramowania sprzęgającego występują podczas jego wykonywania. Na przykład jeśli łącznik nie może przeanalizować odpowiedzi API podczas wykonywania funkcji getData().
Należy przewidywać te błędy i w stosownych przypadkach podawać użytkownikom zrozumiałe wyjaśnienia.
Więcej informacji o obsłudze błędów wewnętrznych łącznika znajdziesz w artykule Sprawdzone metody obsługi błędów łącznika.
Zewnętrzny błąd oprogramowania sprzęgającego
Zewnętrzne błędy oprogramowania sprzęgającego występują po jego wykonaniu. Na przykład gdy żądanie getData() dotyczące 3 pól zwraca dane tylko dla 2 z nich. Chociaż oprogramowanie sprzęgające zakończyło działanie, nie spełniło żądania z Looker Studio. Dokładne testowanie może zapobiec tym błędom.
Błędy zewnętrzne łącznika można zwykle naprawić, sprawdzając szczegóły błędu (jeśli są dostępne) i debugując kod, aby zidentyfikować problem. Więcej informacji o debugowaniu oprogramowania sprzęgającego znajdziesz w artykule Debugowanie kodu.
Błąd Looker Studio
Błędy Looker Studio to błędy niezwiązane z kodem oprogramowania sprzęgającego. Na przykład, jeśli użytkownik spróbuje użyć wykresu serii czasowej ze źródłem danych, które nie zawiera wymiaru daty/godziny.
Jeśli błąd nie jest bezpośrednio związany z oprogramowaniem sprzęgającym, deweloper oprogramowania sprzęgającego nie musi podejmować żadnych działań. Dodatkową pomoc użytkownicy znajdą w Centrum pomocy Looker Studio.
Wyświetlanie komunikatów o błędach
Wyświetlanie szczegółów błędu na podstawie stanu administratora
Gdy oprogramowanie sprzęgające zgłosi błąd, Looker Studio wyświetli komunikat o błędzie w zależności od stanu administratora użytkownika.
- Jeśli użytkownik jest administratorem, zobaczy wszystkie szczegóły. Obejmuje to komunikat o błędzie, typ błędu i ślad stosu.
- Jeśli użytkownik nie jest administratorem, zobaczy szczegóły tylko wtedy, gdy błąd zawiera przyjazny dla użytkownika komunikat. Więcej informacji o wyświetlaniu komunikatów o błędach użytkownikom, którzy nie są administratorami, znajdziesz w artykule Wyświetlanie błędów użytkownikom.
Wyświetlanie błędów użytkownikowi
Domyślnie tylko administratorzy łącznika widzą szczegóły błędów. Pomaga to zapobiegać przypadkowemu ujawnieniu informacji poufnych, takich jak klucz interfejsu API w śladzie stosu. Aby wyświetlać komunikaty o błędach użytkownikom bez uprawnień administratora, użyj funkcji newUserError() z usługi Apps Script w Looker Studio.
Przykład:
try {
// API request that can be malformed.
getDataFromAPI();
} catch (e) {
DataStudioApp.createCommunityConnector()
.newUserError()
.setDebugText('Error fetching data from API. Exception details: ' + e)
.setText('There was an error communicating with the service. Try again later, or file an issue if this error persists.')
.throwException();
}
W tym przykładzie setText() ustawia tekst, który będzie wyświetlany wszystkim użytkownikom, a setDebugText() ustawia tekst, który będzie wyświetlany tylko administratorom.
Sprawdzone metody obsługi błędów łącznika
Podczas wykonywania kodu oprogramowania sprzęgającego należy wychwytywać i obsługiwać jak najwięcej błędów. Oto kilka przykładów typowych operacji, które mogą powodować błędy lub niepożądany stan:
- Nieudana próba pobrania adresu URL (błędy przejściowe, przekroczenie limitu czasu)
- Brak dostępnych danych dla wybranego okresu
- Nie można przeanalizować ani sformatować danych z interfejsu API
- Tokeny autoryzacyjne zostały unieważnione
Obsługa błędów, które można naprawić
Punkty wykonania oprogramowania sprzęgającego, w których może wystąpić błąd, ale które można przywrócić, powinny być obsługiwane. Jeśli na przykład żądanie do interfejsu API nie powiedzie się z powodu niekrytycznego (np. przeciążenia serwera), należy ponowić próbę przed zgłoszeniem błędu.
Przechwytywanie i zgłaszanie błędów
Błędy, których nie można naprawić, należy przechwycić i ponownie zgłosić. Ponownie zgłoszony błąd powinien pomóc użytkownikom zrozumieć, dlaczego wystąpił. Jeśli problem można rozwiązać, należy podać szczegóły dotyczące działań naprawczych.
Zobacz zgłaszanie błędów widocznych dla użytkownika.
Logowanie błędów w Stackdriverze
Używaj Stackdriver do rejestrowania błędów i innych komunikatów. Pomaga to w rozumieniu błędów, debugowaniu problemów i wykrywaniu nieobsłużonych wyjątków.
Więcej informacji o usłudze Stackdriver Error Reporting, włączaniu logowania wyjątków w skrypcie i bezpiecznym identyfikowaniu użytkowników na potrzeby debugowania znajdziesz w artykule Korzystanie z usługi Stackdriver Logging.
WYCOFANE: używaj prefiksu DS_USER: w przypadku bezpiecznych komunikatów o błędach
Aby wyświetlać użytkownikom bez uprawnień administracyjnych przyjazne komunikaty o błędach, dodaj do nich prefiks DS_USER:. Ten prefiks służy do identyfikowania bezpiecznych komunikatów dla użytkowników bez uprawnień administracyjnych i nie jest uwzględniany w rzeczywistym komunikacie o błędzie.
Poniżej znajdziesz przykłady sytuacji, w których komunikat o błędzie będzie wyświetlany użytkownikom bez uprawnień administracyjnych, oraz sytuacji, w których będzie on wyświetlany tylko użytkownikom z uprawnieniami administracyjnymi: