Obsługa błędów i komunikaty dotyczące społecznościowego oprogramowania sprzęgającego

W trosce o wygodę użytkowników kod powinien prawidłowo naprawiać błędy. Wyświetl użytkownikom komunikaty o błędach z instrukcjami, jak naprawić problem.

W tym dokumencie opisujemy błędy, które mogą wystąpić w oprogramowaniu sprzęgającym, sposób działania komunikatów o błędach i prawidłową obsługę błędów oprogramowania sprzęgającego.

Informacja: więcej informacji o obsłudze wyjątków w JavaScript znajdziesz w sekcji instrukcja try...catch.

Rodzaje błędów

Rodzaje i przyczyny błędów, które mogą napotkać użytkownicy podczas korzystania z oprogramowania sprzęgającego, zwykle zaliczają się do jednej z tych trzech kategorii:

1. błędy wewnętrzne oprogramowania sprzęgającego
2. błędy zewnętrznego oprogramowania sprzęgającego
3. Błędy Looker Studio

Błędy wewnętrzne i zewnętrzne oprogramowania sprzęgającego powinny być obsługiwane przez programistę oprogramowania sprzęgającego. Te błędy występują z powodu kodu utworzonego przez dewelopera.

Błąd wewnętrzny oprogramowania sprzęgającego

Podczas wykonywania oprogramowania sprzęgającego występują wewnętrzne błędy oprogramowania sprzęgającego. Jest tak na przykład wtedy, gdy oprogramowanie sprzęgające nie może przeanalizować odpowiedzi interfejsu API podczas wykonywania instrukcji getData(). Błędy te należy przewidzieć i poradzić sobie z nimi, podając przystępne wyjaśnienia.

Więcej informacji o postępowaniu z błędami wewnętrznymi oprogramowania sprzęgającego znajdziesz w artykule Sprawdzone metody postępowania z błędami oprogramowania sprzęgającego.

Zewnętrzny błąd oprogramowania sprzęgającego

Zewnętrzne błędy oprogramowania sprzęgającego występują po wykonaniu działania oprogramowania sprzęgającego. Jeśli na przykład żądanie getData() obejmujące 3 pola zwróci dane tylko dla 2 pól. Chociaż oprogramowanie sprzęgające zostało ukończone, nie spełniło ono żądania z Looker Studio. Dokładne testy mogą zapobiec tym błędom.

Zewnętrzne błędy oprogramowania sprzęgającego można zwykle naprawić przez sprawdzenie szczegółów błędu (jeśli są dostępne) i debugowanie kodu w celu zidentyfikowania problemu. 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 wtedy, gdy użytkownik próbuje użyć wykresu z serią czasową ze źródłem danych bez wymiaru daty/godziny.

Jeśli błąd nie jest bezpośrednio związany z oprogramowaniem sprzęgającym, deweloper nie musi nic robić. Użytkownicy mogą znaleźć dodatkowe wsparcie w Centrum pomocy Looker Studio.

Wyświetlam komunikaty o błędach

Wyświetlanie szczegółów błędów na podstawie stanu administratora

Gdy oprogramowanie sprzęgające zgłasza błąd, Looker Studio wyświetla komunikat o błędzie zależnie od statusu administratora użytkownika.

• Jeśli użytkownik jest administratorem, zobaczy wszystkie informacje. Obejmuje to komunikat o błędzie, typ błędu i zrzut stosu.
• Jeśli użytkownik nie jest administratorem, zobaczy szczegóły tylko wtedy, gdy błąd zawiera komunikat przydatny. Więcej informacji o wyświetlaniu komunikatów o błędach użytkownikom niebędącym administratorami znajdziesz w artykule Zgłaszanie błędów napotykanych przez użytkowników.

Ważne: wdrożyj isAdminUser() w celu wskazania administratorów, aby użytkownicy oprogramowania sprzęgającego widzieli odpowiedni poziom szczegółów.

Zgłaszanie błędów napotykanych przez użytkowników

Domyślnie tylko administratorzy oprogramowania sprzęgającego widzą szczegóły błędu. Pomaga to zapobiegać przypadkowemu ujawnieniu informacji poufnych, takich jak klucz interfejsu API w śladzie stosu. Aby wyświetlić komunikaty o błędach użytkownikom niebędącym administratorami, użyj funkcji newUserError() z usługi Looker Studio Apps Script.

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() – tekst widoczny tylko dla administratorów.

Sprawdzone metody postępowania z błędami oprogramowania sprzęgającego

Podczas wykonywania kodu oprogramowania sprzęgającego postaraj się wychwycić i obsłużyć jak najwięcej błędów. Do typowych operacji, które mogą powodować błędy lub niepożądane stany, należą:

• Nieudana próba pobrania adresu URL (przejściowe błędy, przekroczenie limitu czasu)
• Brak dostępnych danych z wybranego okresu
• Nie można przeanalizować ani sformatować danych z interfejsu API
• Tokeny autoryzacji zostały unieważnione

Postępowanie w przypadku błędów możliwych do naprawienia

Musisz obsługiwać punkty wykonania oprogramowania sprzęgającego, które mogą się nie powieść, ale można je przywrócić. Jeśli na przykład żądania do interfejsu API kończą się niepowodzeniem z przyczyn niekrytycznych (np. z powodu obciążenia serwera), należy ponowić próbę przed wystąpieniem błędu.

Błędy wychwytywania i rzucania

Błędy niemożliwe do naprawy powinny zostać wykryte i zgłoszone ponownie. Powinien on pomóc użytkownikom zrozumieć, dlaczego wystąpił błąd. Jeśli problem można rozwiązać, należy podać szczegółowe informacje na temat działań naprawczych.

Zobacz Zgłaszanie błędów napotykanych przez użytkowników.

Loguj błędy w usłudze Stackdriver

Używaj Stackdrivera do rejestrowania błędów i innych komunikatów. Pomaga to analizować błędy, debugować problemy i wykrywać nieobsłużone wyjątki.

Więcej informacji o usłudze Stackdriver Error Reporting, sposobach włączania logowania wyjątków w skrypcie oraz bezpiecznej identyfikacji użytkowników na potrzeby debugowania znajdziesz w artykule o korzystaniu z usługi Stackdriver Logging.

WYCOFANE: użyj prefiksu DS_USER: na potrzeby bezpiecznych komunikatów o błędach

Uwaga: ta funkcja została wycofana i zostanie usunięta w czerwcu 2019 r. Przeprowadź migrację do newUserError(). Więcej informacji znajdziesz w sekcji Zgłaszanie błędów zgłaszanych przez użytkowników.

Aby wyświetlać komunikaty o błędach użytkownikom niebędącym administratorami, dodaj prefiks DS_USER: z komunikatami o błędach. Ten prefiks służy do identyfikowania wiadomości bezpiecznych dla użytkowników niebędących administratorami i nie jest uwzględniany w rzeczywistym komunikacie o błędzie.

W poniższych przykładach wyświetlany jest komunikat o błędzie użytkownikom niebędącym administratorami, a komunikat o błędzie widoczny tylko dla administratorów:

data-studio/errors.gs

Wyświetl w GitHubie

// Admin and non-admin users will see the following error.
try {
  // Code that might fail.
} catch (e) {
  throw new Error('DS_USER:This will be shown to admin & non-admin.');
}

// Only admin users will see the following error.
try {
  // Code that might fail.
} catch (e) {
  throw new Error('This message will only be shown to admin users');
}

Uwaga: prefiks DS_USER: określa tylko bezpieczne komunikaty dla użytkowników, którzy nie są administratorami. Nie jest on uwzględniony w rzeczywistym komunikacie o błędzie wyświetlanym użytkownikom.