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

Aby zapewnić użytkownikom dobre wrażenia, 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.

Z tego dokumentu dowiesz się, jakie błędy mogą wystąpić w przypadku oprogramowania sprzęgającego, jak działają komunikaty o błędach i jak prawidłowo je obsługiwać.

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:

  1. wewnętrzne błędy łącznika,
  2. błędy zewnętrzne łącznika
  3. [Błędy Studia danych]

Błędy wewnętrzne i zewnętrzne łącznika powinny być obsługiwane przez dewelopera łącznika. 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ć takie 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ż łącznik zakończył działanie, nie spełnił prośby Studia danych. 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 Studia danych

Błędy Studio danych nie są związane z kodem łącznika. Na przykład, jeśli użytkownik spróbuje użyć wykresu ciągu czasowego 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ń. Dodatkowe informacje znajdziesz w [Centrum pomocy Studia danych].

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, Studio danych 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 zrzut 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 sekcji 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 Studio danych.

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() określa tekst, który będzie wyświetlany wszystkim użytkownikom, a setDebugText() określa 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 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 można go naprawić, powinny być obsługiwane. Jeśli na przykład żądanie 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ć, podaj szczegóły dotyczące działań naprawczych.

Zobacz wyświetlanie błędów użytkownikom.

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, rozwiązywaniu 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:

data-studio/errors.gs
function showErrorToAllUsers() {
  try {
    // Code that might fail.
    throw new Error("Something went wrong");
  } catch (e) {
    throw new Error("DS_USER:This will be shown to admin & non-admin.");
  }
}

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