Fehlerbehebung beim Looker Extension Framework

Mit dem Extension Framework von Looker können Sie benutzerdefinierte JavaScript- und TypeScript-Anwendungen und -Visualisierungen erstellen, die in Looker ausgeführt werden. Erweiterungen werden in einer Sandbox-iframe ausgeführt und interagieren über das Extension SDK mit Ihrer Looker-Instanz. Wenn Sie Probleme mit einer benutzerdefinierten Erweiterung haben, z. B. eine leere Seite oder eine Fehlermeldung im iframe, JavaScript- oder CORS-Fehler (Cross-Origin Resource Sharing) in der Browserkonsole, fehlgeschlagene Looker API-Anfragen (Statuscodes 4xx oder 5xx) oder manifest.lkml-Konfigurationsfehler, finden Sie in diesem Dokument Informationen zur Fehlerbehebung.

Voraussetzungen und allgemeine Konfigurationsanforderungen

Bevor Sie mit der Fehlerbehebung beginnen, prüfen Sie, ob Ihre Umgebung, Ihr LookML-Projekt und Ihr Nutzerkonto die Anforderungen für die Ausführung einer Looker-Erweiterung erfüllen:

  • Erweiterungs-Framework aktiviert: Ein Looker-Administrator muss die Einstellung Erweiterungs-Framework unter Admin > Plattform > Erweiterungs-Framework aktivieren.
  • LookML-Projekt- und Modellkonfiguration: Jede Erweiterung erfordert ein LookML-Projekt, das die folgenden Komponenten enthält:
  • Manifestberechtigungen: In der Deklaration application in der Datei manifest.lkml müssen alle entitlements, die die Erweiterung benötigt, explizit definiert werden, z. B. core_api_methods für Looker API-Aufrufe oder external_api_urls für Anfragen an externe Domains. Eine Erweiterung wird ohne einen entitlements-Block nicht ausgeführt.
  • Nutzerberechtigungen: Nutzer müssen Erweiterungsberechtigungen (z. B. access_data, explore oder develop) für einen Modellsatz haben, der das LookML-Modell der Erweiterung enthält. Zum Erstellen einer Erweiterung benötigen Entwickler die LookML-Berechtigung develop.
  • Diagnosetools und Umgebungsdetails: Halten Sie die folgenden Details und Tools bereit, bevor Sie mit der Fehlerbehebung beginnen:
    • Die URL Ihrer Looker-Instanz, der Name des LookML-Projekts und der Name des application, der in manifest.lkml deklariert ist.
    • Zugriff auf die Entwicklertools Ihres Webbrowsers (Tabs Konsole und Netzwerk) auf dem Clientcomputer.
    • Während der lokalen Entwicklung Zugriff auf das Terminal, auf dem Ihr lokaler Entwicklungsserver ausgeführt wird.
    • Bei 5xx-Serverfehlern bei Looker API-Aufrufen: Zugriff auf Looker-Instanzlogs (looker.log auf vom Kunden gehosteten Instanzen oder Log-Explorer in Cloud Logging in der Google Cloud Console für Looker (Google Cloud Core)-Instanzen).

Debugging-Baum

Verwenden Sie den folgenden Entscheidungsbaum, um mit der Fehlerbehebung bei Problemen mit dem Looker Extension Framework zu beginnen:

In den folgenden Abschnitten werden die Szenarien im Baumdiagramm ausführlicher beschrieben.

Browserkonsole und Netzwerkprotokolle prüfen

Da Looker-Erweiterungen clientseitig in Ihrem Browser ausgeführt werden, sollten Sie mit der Fehlerbehebung beginnen, indem Sie die Entwicklertools Ihres Browsers auf JavaScript-Fehler, Richtlinienverstöße und fehlgeschlagene HTTP-Anfragen prüfen.

Browserkonsole auf Fehler prüfen

So identifizieren Sie clientseitige Fehler, die das Laden oder Ausführen der Erweiterung verhindern:

  1. Öffnen Sie in Looker die Seite, auf der die Erweiterung geladen wird.
  2. Rechtsklicken Sie auf eine beliebige Stelle auf der Seite und wählen Sie dann Untersuchen aus. Alternativ können Sie unter Windows und Linux Strg + Umschalttaste + I oder unter macOS Befehlstaste + Wahltaste + I drücken.
  3. Wählen Sie im Bereich „Entwicklertools“ den Tab Konsole aus.
  4. Aktualisieren Sie die Seite, um Fehler zu erfassen, die beim ersten Laden auftreten.
  5. Prüfen Sie alle roten Fehlermeldungen in der Konsole:

Tab „Netzwerk“ auf fehlgeschlagene Anfragen prüfen

So analysieren Sie HTTP-Anfragen, die von der Erweiterung für JavaScript-Bundles, Assets oder API-Endpunkte gestellt werden:

  1. Wählen Sie im Bereich „Entwicklertools“ des Browsers den Tab Netzwerk aus.
  2. Klicken Sie das Kästchen Disable cache an, damit der Browser keine veralteten im Cache gespeicherten Ressourcen lädt.
  3. Aktualisieren Sie die Seite, auf der die Erweiterung geladen wird.
  4. Suchen Sie in der Liste der Netzwerkanfragen nach Statuscodes vom Typ 4xx oder 5xx und wählen Sie eine fehlgeschlagene Anfrage aus, um die Tabs Header, Nutzlast und Antwort zu prüfen:
    • 404 im Erweiterungs-Bundle (z. B. bundle.js): Prüfen Sie, ob der Entwicklungsserver ausgeführt wird und ob der Parameter url oder file in manifest.lkml korrekt ist.
    • 401 oder 403 bei einer Looker API-Anfrage: Prüfen Sie Authentifizierung, Berechtigungen und Zugriffsrechte.
    • 400 oder 422 bei einer API-Anfrage: Prüfen Sie die Tabs Nutzlast und Antwort, um fehlerhaftes JSON oder ungültige Anfrageparameter zu identifizieren.
    • 5xx-Serverfehler: Weisen auf serverseitige Fehler in der Looker-Instanz hin. Suchen Sie in looker.log auf vom Kunden gehosteten Instanzen oder im Log-Explorer in der Console für Looker (Google Cloud Core)-Instanzen nach Einträgen mit übereinstimmenden Zeitstempeln.

Wenn auf den Tabs Konsole oder Netzwerk keine Fehler angezeigt werden oder Sie prüfen möchten, wie Looker die Erweiterung lädt, fahren Sie mit dem nächsten Abschnitt fort.

Manifest und Projektkonfiguration prüfen

Die application-Deklaration in der manifest.lkml-Datei Ihres Projekts steuert, wie Looker die Erweiterung lädt und welche Ressourcen die Erweiterung verwenden kann. Fehlkonfigurationen in manifest.lkml sind eine häufige Ursache für Lade- und API-Fehler:

  • Parameter url oder file prüfen: Öffnen Sie in der Looker-IDE die manifest.lkml-Datei Ihres Projekts und prüfen Sie die application-Deklaration:
    • Eine application-Deklaration muss entweder einen url-Parameter oder einen file-Parameter enthalten, aber nicht beide.
    • Während der lokalen Entwicklung: Prüfen Sie, ob der Parameter url genau mit dem Protokoll (http oder https), dem Hostnamen, dem Port und dem Pfad übereinstimmt, die von Ihrem lokalen Entwicklungsserver bereitgestellt werden (z. B. https://localhost:8080/bundle.js).
    • In der Produktion: Prüfen Sie, ob Sie die application-Deklaration in Ihrem LookML-Projekt (z. B. file: "apps/bundle.js") oder in der URL des Produktions-Bundles vom lokalen Entwicklungspfad url auf den Produktionspfad file aktualisiert haben.
  • manifest.lkml-Berechtigungen prüfen: Sehen Sie sich den Block entitlements in Ihrer application-Deklaration an. Eine Erweiterung kann eine Looker-Ressource oder eine externe Domain nur verwenden, wenn diese Berechtigung explizit deklariert wurde:
    • core_api_methods: Hier müssen alle Looker API-Methoden aufgeführt werden, die von Ihrer Erweiterung aufgerufen werden (z. B. core_api_methods: ["me", "all_looks", "run_inline_query"]).
    • external_api_urls: Hier müssen alle externen, nicht zu Looker gehörenden Domains aufgeführt werden, die die Erweiterung direkt oder über den Proxy anfordert.
    • Zusätzliche Berechtigungen: Prüfen Sie, ob Ihre Erweiterung local_storage, navigation, new_window, new_window_external_urls, use_form_submit, use_embeds, use_downloads, use_iframes, use_clipboard, oauth2_urls, global_user_attributes oder scoped_user_attributes benötigt.
  • Validieren, Commit durchführen und bereitstellen: Klicken Sie nach dem Bearbeiten von manifest.lkml auf LookML validieren, führen Sie einen Commit für Ihre Änderungen durch und klicken Sie auf Für Produktion bereitstellen, damit die aktualisierte Konfiguration wirksam wird.

Fehlerbehebung für den lokalen Entwicklungsserver und die Umgebung

Wenn Sie eine Erweiterung lokal mit dem Parameter url in manifest.lkml entwickeln, muss Ihr lokaler Entwicklungsserver ausgeführt werden und über Ihren Browser zugänglich sein:

  • Prüfen Sie, ob der Entwicklungsserver ausgeführt wird: Sehen Sie im Terminalfenster nach, in dem Sie den Entwicklungsserver gestartet haben (z. B. mit yarn develop oder npm start):
    • Prüfen Sie, ob der Build ohne Fehler kompiliert wurde und eine Meldung angezeigt wird, dass er auf Anfragen wartet (z. B. webpack compiled successfully oder listening on localhost:8080).
    • Wenn der Server nicht ausgeführt wird, starten Sie ihn mit yarn develop oder npm start.
    • Wenn der Server mit einem Syntaxfehler oder einem Fehler aufgrund einer fehlenden Abhängigkeit beendet wurde, beheben Sie den Codefehler oder führen Sie yarn install (oder npm install) aus, um fehlende Pakete zu installieren.
    • Wenn der Server aufgrund eines Portkonflikts (EADDRINUSE) fehlschlägt, beenden Sie den anderen Prozess, der diesen Port verwendet, oder konfigurieren Sie Ihren Entwicklungsserver und den Parameter manifest.lkml url so, dass ein anderer Port verwendet wird.
  • Erweiterungs-URL direkt im Browser öffnen: Kopieren Sie den Wert url aus manifest.lkml (z. B. https://localhost:8080/bundle.js) und öffnen Sie ihn in einem neuen Browsertab:
    • Nicht vertrauenswürdiges selbst signiertes SSL-Zertifikat: Lokale Entwicklungsserver verwenden häufig selbst signierte SSL-Zertifikate. Wenn Ihr Browser eine Sicherheitswarnung für das Zertifikat anzeigt, wählen Sie Erweitert aus und fahren Sie mit localhost fort, um dem Zertifikat für Ihre Browsersitzung zu vertrauen. Bis das Zertifikat als vertrauenswürdig eingestuft wird, blockiert der Browser das Laden des Bundles in der Looker-iframe.
    • Verbindung abgelehnt oder blockiert: Wenn der Browser die URL nicht erreichen kann, prüfen Sie, ob eine lokale Firewall oder Endpunktsicherheitssoftware Verbindungen zu localhost über den konfigurierten Port blockiert.

Probleme mit Netzwerken, CORS und Sicherheitsrichtlinien beheben

Webbrowser erzwingen die Same-Origin Policy, die verhindert, dass Looker Erweiterungsressourcen lädt oder externe Server mit einem anderen Ursprung aufruft, es sei denn, CORS-Header (Cross-Origin Resource Sharing) und Sicherheitsrichtlinien sind konfiguriert:

  • CORS-Fehler in der Browserkonsole identifizieren: Suchen Sie auf dem Tab Konsole nach Fehlermeldungen, die Cross-Origin Resource Sharing, CORS, has been blocked by CORS policy oder fehlende Access-Control-Allow-Origin-Header enthalten.
  • CORS-Header für den lokalen Entwicklungsserver konfigurieren: Wenn Sie webpack-dev-server (oder einen ähnlichen Bundler) verwenden, muss die devServer-Konfiguration in webpack.config.js den Access-Control-Allow-Origin-Header enthalten: javascript devServer: { headers: { "Access-Control-Allow-Origin": "*" } }
  • Produktionshosting und CORS-Header für externe APIs konfigurieren: Wenn Ihre Erweiterung Assets lädt oder Daten von einem externen Dienst (z. B. Cloud Storage, Amazon S3 oder einem benutzerdefinierten Backend-Server) anfordert, konfigurieren Sie den Hostingdienst so, dass er den Header Access-Control-Allow-Origin zurückgibt, der die Domain Ihrer Looker-Instanz zulässt. Prüfen Sie außerdem, ob ein Netzwerkproxy oder eine Firewall CORS-Header aus der Antwort entfernt, und ob die externe Domain in external_api_urls in manifest.lkml aufgeführt ist.
  • Content Security Policy (CSP) und erweitertes Laden von Erweiterungen prüfen: Wenn beim Laden einer Erweiterung CSP-Verstöße auftreten, prüfen Sie die Einstellung Erweitertes Laden von Erweiterungen unter Admin > Plattform > Erweiterungs-Framework.

Probleme bei der Authentifizierung und beim API-Zugriff beheben

Erweiterungen interagieren über das Extension SDK im Namen des angemeldeten Nutzers mit der Looker API. Wenn API-Aufrufe mit den Statuscodes 401 Unauthorized oder 403 Forbidden auf dem Tab Netzwerk fehlschlagen, prüfen Sie Folgendes:

  • Unterscheiden Sie zwischen 401- und 403-Fehlern:
    • 401 Unauthorized: Die Anfrage wurde nicht authentifiziert. Dieser Fehler tritt in der Regel auf, wenn das Extension SDK nicht richtig initialisiert wurde oder wenn die Erweiterung einen API-Aufruf versucht hat, bevor das SDK den Authentifizierungs-Handshake abgeschlossen hat.
    • 403 Forbidden: Die Anfrage wurde authentifiziert, aber entweder verfügt der angemeldete Nutzer nicht über die erforderlichen Looker-Berechtigungen oder die manifest.lkml der Erweiterung enthält die aufgerufene Methode nicht in core_api_methods.
  • Nutzerrollen und -berechtigungen prüfen: Prüfen Sie unter Verwaltung > Nutzer und Verwaltung > Rollen die zugewiesenen Rollen, Berechtigungssätze und Modellsätze des angemeldeten Nutzers:
    • Prüfen Sie, ob der Nutzer die Berechtigungen zur Verwendung der Erweiterung hat, einschließlich access_data (und explore oder develop nach Bedarf) für einen Modellsatz, der das LookML-Modell der Erweiterung und alle Modelle enthält, die von der Erweiterung abgefragt werden.
    • Prüfen Sie, ob die Rolle des Nutzers die spezifischen Berechtigungen enthält, die für jeden Looker API-Endpunkt erforderlich sind, der von der Erweiterung aufgerufen wird.
  • Achten Sie darauf, dass der SDK-Kontext bereit ist, bevor Sie die API aufrufen: Prüfen Sie, ob Ihr Erweiterungscode auf die Initialisierung des Extension SDK-Kontexts wartet, bevor API-Methoden aufgerufen werden.

Fehlerbehebung für das Erweiterungs-SDK und Abhängigkeiten

Probleme bei der Installation von npm- oder Yarn-Paketen oder fehlende SDK-Anbieterkomponenten können verhindern, dass eine Erweiterung kompiliert oder eine Verbindung zu Looker hergestellt wird:

  • Installation des Node.js-Moduls prüfen: Rufen Sie im Terminal das Stammverzeichnis Ihres Erweiterungsprojekts auf und prüfen Sie das Verzeichnis node_modules:
    1. Wenn node_modules fehlt oder Abhängigkeiten beschädigt sind, löschen Sie das Verzeichnis node_modules und die Sperrdatei (yarn.lock oder package-lock.json).
    2. Optional: Wenn die Paketinstallation wiederholt fehlschlägt, leeren Sie den Cache des Paketmanagers (führen Sie z. B. npm cache clean --force aus).
    3. Prüfen Sie, ob die installierte Node.js-Version mit den Anforderungen des Projekts kompatibel ist, und führen Sie dann yarn install oder npm install aus, um eine Neuinstallation durchzuführen.
  • ExtensionProvider-Initialisierung prüfen: Öffnen Sie die Haupteintragsdatei Ihrer Erweiterung (z. B. App.js oder index.js) und prüfen Sie, ob <ExtensionProvider> (importiert aus @looker/extension-sdk-react) die Anwendungskomponenten umschließt, die den Looker SDK-Kontext benötigen: javascript ReactDOM.render( <ExtensionProvider> <App /> </ExtensionProvider>, document.getElementById('root') ); Wenn <ExtensionProvider> fehlt oder Sie es nach Komponenten platziert haben, die das SDK aufrufen, können untergeordnete Komponenten nicht auf den SDK-Kontext zugreifen.

JavaScript- und Logikfehler zur Laufzeit beheben

Wenn die Konfiguration, der Entwicklungsserver, die Berechtigungen und die SDK-Einrichtung der Erweiterung gültig sind, liegt das Problem möglicherweise an einem Laufzeitfehler im benutzerdefinierten JavaScript- oder TypeScript-Code der Erweiterung:

  • Stacktraces in der Console analysieren: Suchen Sie im Browser auf dem Tab Console nach der roten Fehlermeldung und klicken Sie auf den Pfeil zum Maximieren, um den vollständigen Stacktrace aufzurufen. In den obersten Zeilen des Stacktrace werden die Datei und die Zeilennummer in Ihrem Quellcode angegeben, in der der Fehler aufgetreten ist. Klicken Sie auf den Dateilink (z. B. MyComponent.js:42), um direkt zu dieser Zeile auf dem Tab Quellen zu springen.
  • Auf nicht definierte oder Nullwerte prüfen: Bei Fehlern wie TypeError: Cannot read properties of undefined sollten Sie prüfen, ob asynchrone API-Antworten oder Props vollständig geladen wurden, bevor Ihr Code verschachtelte Attribute liest. Fügen Sie defensive Prüfungen hinzu (z. B. if (myObject && myObject.property) oder optionale Verkettung myObject?.property).
  • API-Antwortformate prüfen: Bestätigen Sie, dass Ihr Code die tatsächliche Datenstruktur verarbeitet, die von Looker API-Aufrufen zurückgegeben wird. Prüfen Sie beispielsweise, ob eine Antwortnutzlast ein Objekt oder ein Array ist, bevor Sie Array-Methoden aufrufen.
  • Mit Haltepunkten und Logging debuggen: Setzen Sie im Browser auf dem Tab Quellen Haltepunkte vor der fehlerhaften Zeile, um die Ausführung zu pausieren und Variablenwerte in Echtzeit zu prüfen. Alternativ können Sie console.log()-Anweisungen hinzufügen, um den Ausführungsablauf zu verfolgen.

Kompatibilität der Looker-Version prüfen

Wichtige Funktionsupdates oder Änderungen in Looker können eine kompatible Version des Looker Extension SDK erfordern:

  1. Prüfen Sie die Version von @looker/extension-sdk (und @looker/extension-sdk-react, falls verwendet) in der Datei package.json Ihres Erweiterungsprojekts.
  2. Prüfen Sie in der Looker-Weboberfläche die aktuelle Release-Version Ihrer Instanz unter Hilfe > Info oder Verwaltung > Allgemein > Einstellungen.
  3. Vergleichen Sie Ihre Looker-Release-Version mit den Kompatibilitätshinweisen in der @looker/extension-sdk-Dokumentation.
  4. Wenn Ihre Looker-Instanz vor Kurzem aktualisiert wurde und die Erweiterung ein veraltetes SDK verwendet oder wenn die Erweiterung ein neueres SDK-Feature verwendet, das von einer früheren Looker-Version nicht unterstützt wird, aktualisieren Sie das SDK-Paket auf eine kompatible Version: bash npm install @looker/extension-sdk@latest Nachdem Sie das Paket aktualisiert haben, installieren Sie die Abhängigkeiten neu und starten Sie Ihren Entwicklungsserver neu.

Diagnoseinformationen erfassen

Wenn Sie das Problem nach den Schritten zur Fehlerbehebung nicht beheben können, erfassen Sie die folgenden Informationen, bevor Sie sich an den Support wenden:

  1. Informationen zur Looker-Instanz und zum Projekt:
    • Looker-Instanz-URL (z. B. instance_name.looker.com).
    • Looker-Release-Version.
    • Name des LookML-Projekts, das die Erweiterung enthält, und der Name von application in manifest.lkml.
  2. Erweiterungskonfiguration und SDK-Details:
    • Eine Kopie oder einen Screenshot der application-Deklaration in der Datei manifest.lkml.
    • Die Version von @looker/extension-sdk, die in package.json angegeben ist.
    • Gibt an, ob die Erweiterung auf einem lokalen Entwicklungsserver (url) ausgeführt oder in der Produktion (file) bereitgestellt wird.
  3. Fehlerprotokolle und Screenshots:
    • Screenshots oder vollständiger Text von Fehlern auf den Tabs Konsole und Netzwerk des Browsers (einschließlich Anfrageheadern und Antwortnutzlasten für fehlgeschlagene 4xx- oder 5xx-Anfragen).
    • Wenn API-Aufrufe durchgängig 5xx-Serverfehler zurückgeben, entsprechende Logauszüge aus looker.log (für vom Kunden gehostete Instanzen) oder Log-Explorer in Logging (für Looker (Google Cloud Core)-Instanzen).
  4. Zusammenfassung der Fehlerbehebung und Schritte zur Reproduktion:
    • Eine Zusammenfassung der Schritte zur Fehlerbehebung, die Sie bereits ausgeführt haben, und deren Ergebnisse.
    • Genaue Schritte zum Reproduzieren des Problems oder ein minimales reproduzierbares Beispiel, wenn Sie ein Problem im Looker Extension Framework oder Extension SDK vermuten.

Support kontaktieren

Wenn du alle vorherigen Schritte ausgeführt hast und das Problem immer noch nicht behoben ist: