Fehlerbehandlung und Meldungen für Community-Connectors

Damit Nutzer eine gute Erfahrung machen, sollten Fehler in Ihrem Code korrekt behandelt werden. Präsentieren Sie Nutzern umsetzbare Fehlermeldungen, in denen die Schritte zur Behebung des Problems beschrieben werden.

In diesem Dokument werden Fehler beschrieben, die bei Connectors auftreten können, wie Fehlermeldungen funktionieren und wie Connector-Fehler richtig behandelt werden.

Hinweis: Weitere Informationen zur Behandlung von Ausnahmen in JavaScript finden Sie unter try...catch-Anweisung.

Arten von Fehlern

Die Arten und Ursachen von Fehlern, die bei der Verwendung Ihres Connectors auftreten können, lassen sich in der Regel in eine der folgenden drei Kategorien einteilen:

1. Interne Connector-Fehler
2. Externe Connector-Fehler
3. [Data Studio-Fehler]

Interne und externe Connector-Fehler sollten vom Connector-Entwickler behandelt werden. Diese Fehler treten aufgrund von Code auf, der vom Entwickler erstellt wurde.

Interner Connector-Fehler

Interne Connector-Fehler treten während der Ausführung des Connectors auf. Beispiel: Ein Connector kann eine API-Antwort während der Ausführung von getData() nicht parsen. Diese Fehler sollten vorhergesehen und gegebenenfalls mit nutzerfreundlichen Erklärungen behandelt werden.

Weitere Informationen zur Behandlung interner Connector-Fehler finden Sie unter Best Practices für die Behandlung von Connector-Fehlern.

Externer Connector-Fehler

Externe Connector-Fehler treten nach der Ausführung des Connectors auf. Beispiel: Bei einer getData()-Anfrage für drei Felder werden nur Daten für zwei zurückgegeben. Obwohl die Ausführung des Connectors abgeschlossen wurde, wurde die Anfrage von Data Studio nicht erfüllt. Durch gründliche Tests können diese Fehler vermieden werden.

Externe Connector-Fehler können in der Regel behoben werden, indem Sie die Fehlerdetails prüfen (falls verfügbar) und den Code debuggen, um das Problem zu identifizieren. Weitere Informationen zum Debuggen Ihres Connectors finden Sie unter Code debuggen.

Data Studio-Fehler

Data Studio-Fehler sind Fehler, die nicht mit Ihrem Connector-Code zusammenhängen. Beispiel: Ein Nutzer versucht, ein Zeitreihendiagramm mit einer Datenquelle ohne Datums-/Zeitdimension zu verwenden.

Wenn der Fehler nicht direkt mit dem Connector zusammenhängt, muss der Connector-Entwickler nichts unternehmen. Nutzer finden weitere Hilfe in der [Data Studio-Hilfe].

Fehlermeldungen anzeigen

Fehlerdetails basierend auf dem Administratorstatus anzeigen

Wenn ein Connector einen Fehler auslöst, zeigt Data Studio die Fehlermeldung je nach Administratorstatus des Nutzers an.

• Wenn der Nutzer ein Administrator ist, werden alle Details angezeigt. Dazu gehören die Fehlermeldung, der Fehlertyp und der Stacktrace.
• Wenn der Nutzer kein Administrator ist, werden nur Details angezeigt, wenn der Fehler eine nutzerfreundliche Meldung enthält. Weitere Informationen zum Anzeigen von Fehlermeldungen für Nutzer, die keine Administratoren sind, finden Sie unter Fehler für Nutzer auslösen.

Wichtig: Implementieren Sie isAdminUser(), um Administratoren zu identifizieren, damit Connector-Nutzern die richtige Detailtiefe angezeigt wird.

Fehler für Nutzer auslösen

Standardmäßig sehen nur Connector-Administratoren Fehlerdetails. So wird die unbeabsichtigte Offenlegung vertraulicher Informationen verhindert, z. B. eines API-Schlüssels in einem Stacktrace. Verwenden Sie newUserError() aus dem Data Studio Apps Script-Dienst, um Fehlermeldungen für Nutzer anzuzeigen, die keine Administratoren sind.

Beispiel:

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();

}

In diesem Beispiel legt setText() den Text fest, der allen Nutzern angezeigt wird, während setDebugText() den Text festlegt, der nur Administratoren angezeigt wird.

Best Practices für die Behandlung von Connector-Fehlern

Sie sollten versuchen, so viele Fehler wie möglich während der Ausführung Ihres Connector-Codes abzufangen und zu behandeln. Einige häufige Vorgänge, die Fehler oder einen unerwünschten Zustand verursachen können, sind beispielsweise:

• Fehlgeschlagener URL-Abrufversuch (vorübergehende Fehler, Zeitüberschreitungen)
• Für den angeforderten Zeitraum sind keine Daten verfügbar
• Daten aus der API können nicht geparst oder formatiert werden
• Autorisierungstokens wurden widerrufen

Behebbare Fehler behandeln

Punkte der Connector-Ausführung, bei denen Fehler auftreten können, die aber behoben werden können, sollten behandelt werden. Wenn beispielsweise eine API-Anfrage aus einem nicht schwerwiegenden Grund fehlschlägt (z.B. Serverlastverteilung), sollte sie noch einmal versucht werden, bevor ein Fehler ausgelöst wird.

Fehler abfangen und auslösen

Nicht behebbare Fehler sollten abgefangen und erneut ausgelöst werden. Der erneut ausgelöste Fehler sollte Nutzern helfen, die Ursache des Fehlers zu verstehen. Wenn das Problem behoben werden kann, sollten Details zu den Korrekturmaßnahmen angegeben werden.

Weitere Informationen finden Sie unter Fehler für Nutzer auslösen.

Fehler in Stackdriver protokollieren

Verwenden Sie Stackdriver, um Fehler und andere Meldungen zu protokollieren. So können Sie Fehler besser verstehen, Probleme debuggen und nicht behandelte Ausnahmen erkennen.

Weitere Informationen zu Stackdriver Error Reporting, zum Aktivieren der Ausnahme-Protokollierung für ein Skript und zum sicheren Identifizieren von Nutzern zu Debugging-Zwecken finden Sie unter Stackdriver Logging verwenden.

EINGESTELLT: Präfix DS_USER: für sichere Fehlermeldungen verwenden

Achtung: Diese Funktion ist eingestellt und wird im Juni 2019 entfernt. Migrieren Sie zu newUserError(). Weitere Informationen finden Sie unter Fehler für Nutzer auslösen.

Wenn Sie Nutzern, die keine Administratoren sind, nutzerfreundliche Fehlermeldungen präsentieren möchten, fügen Sie den Fehlermeldungen das Präfix DS_USER: hinzu. Dieses Präfix wird verwendet, um sichere Meldungen für Nutzer zu identifizieren, die keine Administratoren sind, und ist nicht in der eigentlichen Fehlermeldung enthalten.

Die folgenden Beispiele enthalten einen Fall, in dem eine Fehlermeldung für Nutzer angezeigt wird, die keine Administratoren sind, und einen Fall, in dem eine Fehlermeldung nur für Administratoren angezeigt wird:

data-studio/errors.gs

Auf GitHub ansehen

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");
  }
}

Hinweis: Das Prä5fix identifiziert nur sichere Meldungen für Nutzer, die keine Administratoren sind, es ist nicht in der eigentlichen Fehlermeldung enthalten, die Nutzern angezeigt wird.

DS_USER: