Fehlerbehandlung und Meldungen für Community-Connectors

Damit Nutzer eine gute Erfahrung machen, sollten Fehler in Ihrem Code richtig behandelt werden. Zeigen Sie den Nutzern umsetzbare Fehlermeldungen an, 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 zum Behandeln von Ausnahmen in JavaScript finden Sie unter try...catch-Anweisung.

Arten von Fehlern

Die Arten und Ursachen von Fehlern, die ein Nutzer bei der Verwendung Ihres Connectors feststellen kann, lassen sich in der Regel einer der folgenden drei Kategorien zuordnen:

1. Interne Connector-Fehler
2. Externe Connector-Fehler
3. Looker Studio-Fehler

Interne und externe Connector-Fehler sollten vom Connector-Entwickler behoben werden. Diese Fehler treten aufgrund von Entwicklercode auf.

Interner Connector-Fehler

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

Weitere Informationen zum Beheben interner Connector-Fehler finden Sie unter Best Practices für die Fehlerbehebung bei Connectors.

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. Der Connector wurde zwar ausgeführt, aber die Anfrage von Looker Studio wurde nicht erfüllt. Durch gründliche Tests können diese Fehler vermieden werden.

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

Looker Studio-Fehler

Looker Studio-Fehler sind Fehler, die nicht mit Ihrem Connector-Code zusammenhängen. Das kann beispielsweise passieren, wenn 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. Weitere Informationen finden Sie in der Looker Studio-Hilfe.

Fehlermeldungen anzeigen

Fehlerdetails basierend auf dem Administratorstatus anzeigen

Wenn ein Connector einen Fehler ausgibt, wird die Fehlermeldung in Looker Studio je nach Administratorstatus des Nutzers angezeigt.

• Wenn der Nutzer ein Administrator ist, werden ihm 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 Nutzerorientierte Fehler auslösen.

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

Nutzerorientierte Fehler auslösen

Standardmäßig sehen nur Connector-Administratoren Fehlerdetails. So wird verhindert, dass vertrauliche Informationen wie ein API-Schlüssel in einem Stacktrace versehentlich offengelegt werden. Wenn Sie Fehlermeldungen für Nutzer anzeigen möchten, die keine Administratoren sind, verwenden Sie newUserError() aus dem Looker Studio Apps Script-Dienst.

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 wird mit setText() der Text festgelegt, der allen Nutzern angezeigt wird, und mit setDebugText() der Text, 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 beheben. Einige häufige Vorgänge, die Fehler oder einen unerwünschten Zustand verursachen können, sind beispielsweise:

• Ein 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, die fehlschlagen, aber wiederhergestellt werden können, sollten behandelt werden. Wenn eine API-Anfrage beispielsweise aus einem nicht schwerwiegenden Grund fehlschlägt (z.B. aufgrund von Server-Load-Shedding), sollte sie wiederholt werden, bevor ein Fehler ausgegeben wird.

Fehler abfangen und ausgeben

Nicht behebbarer Fehler sollten abgefangen und noch einmal ausgelöst werden. Der neu 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 Nutzerorientierte Fehler auslösen.

Fehler in Stackdriver protokollieren

Stackdriver zum Protokollieren von Fehlern und anderen Meldungen verwenden Das hilft dabei, Fehler zu verstehen, Probleme zu beheben und nicht behandelte Ausnahmen zu erkennen.

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

EINGESTELLT: Verwenden Sie das Präfix DS_USER: für sichere Fehlermeldungen.

Achtung :Diese Funktion ist veraltet und wird im Juni 2019 entfernt. Zu newUserError() migrieren Weitere Informationen finden Sie unter Nutzerorientierte Fehler auslösen.

Damit Nutzer, die keine Administratorberechtigungen haben, benutzerfreundliche Fehlermeldungen erhalten, müssen Sie den Fehlermeldungen das Präfix DS_USER: voranstellen. Dieses Präfix wird verwendet, um sichere Nachrichten für Nutzer ohne Administratorberechtigungen zu kennzeichnen. Es ist nicht in der eigentlichen Fehlermeldung enthalten.

In den folgenden Beispielen wird ein Fall beschrieben, in dem Nicht-Administratornutzern eine Fehlermeldung angezeigt wird, und ein Fall, in dem eine Fehlermeldung nur Administratornutzern angezeigt wird:

data-studio/errors.gs

Auf GitHub ansehen

// 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');
}

Hinweis :Das Präfix DS_USER: kennzeichnet nur sichere Nachrichten für Nutzer, die keine Administratoren sind. Es ist nicht in der tatsächlichen Fehlermeldung enthalten, die Nutzern angezeigt wird.