Sie sehen sich die Dokumentation für Looker 22.16 an. Die aktuelle Dokumentation finden Sie hier.

Einführung in das Embed SDK

Das Embed SDK von Looker ist eine Bibliothek mit Funktionen, die Sie zum Code Ihrer browserbasierten Webanwendung hinzufügen können, um eingebettete Dashboards, Looks und Explores in Ihrer Webanwendung zu verwalten. Das Embed SDK ermöglicht die Einbettung auf folgende Arten:

Die Kapselung der eingebetteten Inhalte, ohne dass manuell HTML-Elemente erstellt werden müssen
Punkt-zu-Punkt-Kommunikation für rahmenübergreifende Kommunikation Das Embed SDK verarbeitet die domainübergreifende Nachrichtenweiterleitung zwischen Ihrer Hostwebseite und Ihrem eingebetteten Looker-Inhalt und verwendet einen speziellen Nachrichtenkanal.

Ohne das Embed SDK können Sie Ereignisse in eingebetteten Looker-Inhalten mithilfe von JavaScript-Ereignissen wie dashboard:run:start oder page:changed aufrufen oder darauf reagieren. Diese Ereignisse werden auf der Dokumentationsseite Eingebettete JavaScript-Ereignisse beschrieben. Entwickler, die Looker-Inhalte mit JavaScript-Ereignissen einbetten, müssen die HTML-Elemente erstellen, um die eingebetteten Inhalte zu speichern, und sich für die Kommunikation zwischen der Web-App und den eingebetteten Inhalten auf Fensterübertragungsereignisse verlassen.

Das Looker Embed SDK unterscheidet sich von der Looker API und dem Looker API SDK:

Das Looker Embed SDK befindet sich im clientseitigen Code Ihrer Webanwendung und verwaltet den Looker-Kontext und -Inhalt. Das Embed SDK bietet keinen Zugriff auf die Looker API.
Die Looker API befindet sich auf dem Server mit Ihrer Looker-Instanz und führt Befehle auf dem Looker-Server aus.
Die Looker API-Client-SDKs befinden sich im Code von nicht browsergestützten Anwendungen und ermöglichen einen einfachen Zugriff auf Looker API-Funktionen.

Beachten Sie, dass Looker keine Kontrolle über die Reihenfolge hat, in der Browser Ereignisse an Webanwendungen senden. Das bedeutet, dass die Reihenfolge der Ereignisse nicht browser- oder plattformübergreifend garantiert ist. Achten Sie darauf, Ihren JavaScript-Code so zu schreiben, dass er die Ereignisverarbeitung in verschiedenen Browsern berücksichtigt.

Kurzes Beispiel

In diesem Beispiel wird ein Looker-Einbettungskontext erstellt, in ein DOM-Element mit der ID dashboard eingefügt und dann ein Dashboard mit der ID 11 im eingebetteten Kontext von Looker angezeigt. Mit den Ereignissen dashboard:run:start und dashboard:run:complete wird der Status der Benutzeroberfläche des Einbettungsfensters aktualisiert. Außerdem wird eine Schaltfläche mit der ID run per Skript aufgerufen, um eine dashboard:run-Nachricht an das Dashboard zu senden.

LookerEmbedSDK.init('looker.example.com', '/auth')

const setupDashboard = (dashboard) => {
  document.querySelector('#run').addEventListener('click', () => {
    dashboard.send('dashboard:run')
  })
}

LookerEmbedSDK.createDashboardWithId(11)
  .appendTo('#dashboard')
  .on('dashboard:run:start',
      () => updateState('#dashboard-state', 'Running')
  )
  .on('dashboard:run:complete',
      () => updateState('#dashboard-state', 'Done')
  )
  .build()
  .connect()
  .then(setupDashboard)
  .catch((error: Error) => {
    console.error('An unexpected error occurred', error)
  })

Ein ausführlicheres Beispiel finden Sie auf der Dokumentationsseite Embed SDK-Demo.

Looker Embed SDK einrichten

Das Looker Embed SDK verwendet ein fließendes Schnittstellenmuster. Nachdem du das Embed SDK installiert hast, kannst du den eingebetteten Inhalt erstellen und eine Verbindung zum eingebetteten Inhalt herstellen.

Embed SDK installieren

Die Embed SDK-Bibliothek von Looker finden Sie über den Node Package Manager (NPM) unter https://www.npmjs.com/package/@looker/embed-sdk. Wenn Sie jedoch den Beispielcode oder die Demo sehen möchten, sollten Sie das Repository von Looker Embed SDK verwenden.

So installieren Sie das Looker Embed SDK mit dem Repository „Looker Embed SDK“:

Installieren Sie Node.js, falls noch nicht vorhanden.
Laden Sie das Repository /looker-open-source/embed-sdk herunter oder klonen Sie es.
Wechseln Sie in einem Terminalfenster zum Verzeichnis /embed-sdk und führen Sie die folgenden Befehle aus:

npm install
npm start

Eingebettete Inhalte erstellen

Initialisieren Sie zuerst das SDK mit der Adresse Ihres Webservers und optional des Endpunkts auf Ihrem Server, der die Authentifizierung durchführen soll. Sie werden von allen eingebetteten Inhalten verwendet.

Geben Sie die Portnummer an, wenn der Looker-Server über Browser-Clients erreichbar ist. Beispiel: looker.example.com:443

LookerEmbedSDK.init('looker.example.com', '/auth')

Anschließend werden die Parameter mithilfe einer Reihe von Schritten definiert. Einige dieser Parameter sind optional, andere erforderlich.

Der Prozess beginnt damit, dass der Builder mit einem Dashboard-id oder einem url erstellt wird, das auf ein Dashboard verweist (erstellt durch den Prozess, der auf der Dokumentation zum Einbetten von Einmalanmeldung (SSO) beschrieben wird).

LookerEmbedSDK.createDashboardWithId(id)

oder

LookerEmbedSDK.createDashboardWithUrl(url)

Anschließend können Sie dem Builder weitere Attribute hinzufügen, um die Einrichtung abzuschließen. Sie können beispielsweise angeben, wo auf Ihrer Webseite die Looker-Einbettungs-UI eingefügt werden soll. Mit dem folgenden Aufruf wird die eingebettete Looker-UI in ein HTML-Element mit dem ID-Wert dashboard eingefügt:

.appendTo('#dashboard')

Sie können Ereignis-Handler hinzufügen:

.on('dashboard:run:start',
  () => updateState('#dashboard-state', 'Running')
)
.on('dashboard:run:complete',
  () => updateState('#dashboard-state', 'Done')
)

Zum Abschluss erstellen Sie das eingebettete Element:

.build()

Verbindung zu eingebetteten Inhalten herstellen

Wenn du Nachrichten an das eingebettete Element senden und von ihm empfangen möchtest, musst du connect() aufrufen. Es wird ein Versprechen zurückgegeben, das zur Kommunikationsoberfläche des Elements aufgelöst wird:

.connect()
.then(setupDashboard)
.catch(console.error)

URLs für das SDK erstellen

Die Hauptdokumentation zu eingebetteten URLs in der Looker-SSO finden Sie auf der Dokumentationsseite Einmalanmeldung (SSO) – Einbettung. Der einzige Unterschied beim Erstellen von URLs für das SDK besteht darin, dass du neben eingebetteten Parametern wie Filtern und dem Parameter embed_domain einen sdk=2-Parameter in die Einbettungs-URL einfügen musst. Mit diesem Parameter kann Looker feststellen, ob das SDK vorhanden ist, und zusätzliche Funktionen des SDK nutzen. Beispiel:

/embed/looks/4?embed_domain=https://mywebsite.com&sdk=2
                                                 ^^^^^^

Das SDK kann diesen Parameter nicht selbst hinzufügen, da es Teil der signierten SSO-URL ist.

Auth-Endpunkt

Da das Einbettungs-Secret sorgfältig geschützt werden muss, können eingebettete SSO-URLs nicht im Browser erstellt werden. Sie können diesen Vorgang vereinfachen und vereinfachen:

Implementieren Sie eine URL-Signaturfunktion auf Ihrem Webserver. Der Server sollte eine signierte URL mit einem der Prozesse zurückgeben, die im GitHub-Repository zum Einbinden von SSO-Beispielen dokumentiert sind.
Übergib die eingebettete SSO-URL an diesen Signaturendpunkt im Embed SDK. Der Standort des Endpunkts wird durch den Parameter authUrl in LookerEmbedSDK.init() angegeben.

Wenn angegeben, wird jedes Mal, wenn ein Einbettungselement mit einer ID erstellt wird, die Einbettungs-URL aus dem Elementtyp, dem bereitgestellten Looker-Host und allen bereitgestellten Parametern generiert. Beispiel:

LookerEmbedSDK.init('looker.example.com', '/looker_auth')
LookerEmbedSDK.createcreateDashboardWithId(11)
  .build()

Dadurch wird der Endpunkt /looker_auth aufgerufen und eine signierte SSO-URL zurückgegeben, mit der der eingebettete Inhalt erstellt werden kann:

src=https://looker.example.com/embed/dashboards/11?sdk=2&embed_host=https://yourhost.example.com

Erweiterte Authentifizierungskonfiguration

Der Auth-Endpunkt kann weiter konfiguriert werden, um benutzerdefinierte Anfrageheader sowie CORS-Unterstützung zuzulassen. Dazu übergeben Sie ein Optionsobjekt an die Methode init:


LookerEmbedSDK.init('looker.example.com',
  {
    url: 'https://api.acme.com/looker/auth',
    headers: [{'name': 'Foo Header', 'value': 'Foo'}],
    params: [{'name': 'foo', 'value': 'bar'}],
    withCredentials: true // Needed for CORS requests to Auth endpoint include Http Only cookie headers
  })

Knotenhelfer

In server_utils/auth_utils.ts ist eine Signatur-Assistentmethode createSignedUrl() verfügbar. Die Anwendung sieht so aus:

import { createSignedUrl } from './auth_utils'

app.get('/looker_auth', function(req, res) {
  // TO DO: Add your code here to authenticate that the request is from a valid user
  const src = req.query.src;
  const host = 'https://looker.example.com'
  const secret = YOUR_EMBED_SECRET
  const user = authenticatedUser
  const url = createSignedUrl(src, user, host, secret);
  res.json({ url });
});

Das ist die Struktur der Nutzerdaten:

interface LookerEmbedUser {
  external_user_id: string
  first_name?: string
  last_name?: string
  session_length: number
  force_logout_login?: boolean,
  permissions: LookerUserPermission[]
  models: string[]
  group_ids?: number[]
  external_group_id?: string
  user_attributes?: {[key: string]: any}
  access_filters: {}
}

Der Parameter access_filters wurde in Looker 3.10 entfernt, ist aber weiterhin mit einem leeren Platzhalter in der eingebetteten URL erforderlich.

Fehlerbehebung

Logging

Das Embed SDK basiert auf chatty. Chatty verwendet für die Protokollierung das debug. Mit dem folgenden Befehl können Sie das Logging in einer Browserkonsole aktivieren:

localStorage.debug = 'looker:chatty:*'
```none

Note that both the parent window and the embedded content have separate local storage, so you can enable logging on one, the other, or both. You can disable logging with this command:

```javascript
localStorage.debug = ''