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 des eingebetteten Inhalts wird bereitgestellt, ohne dass manuell HTML-Elemente erstellt werden müssen.
  • Punkt-zu-Punkt-Kommunikation ohne Cross-Frame-Kommunikation Das Embed SDK verarbeitet die domainübergreifende Übertragung von Nachrichten zwischen Ihrer Hostwebseite und Ihren eingebetteten Looker-Inhalten mithilfe eines dedizierten Nachrichtenkanals.

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 werden auf der Dokumentationsseite Eingebettete JavaScript-Ereignisse beschrieben. Entwickler, die Looker-Inhalte mit JavaScript-Ereignissen einbetten, müssen die HTML-Elemente für die eingebetteten Inhalte erstellen und sich bei der Kommunikation zwischen der Webanwendung und den eingebetteten Inhalten auf Fensterübertragungsereignisse verlassen.

Beachten Sie, dass sich das Looker Embed SDK von der Looker API und dem Looker API SDK unterscheidet:

  • Das Looker Embed SDK befindet sich im clientseitigen Code Ihrer Webanwendung und verwaltet den Looker-Kontext und die Inhalte. 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.
  • Looker API-Client-SDKs befinden sich im Code von Nicht-Browser-Anwendungen, um einfachen Zugriff auf Looker API-Funktionen zu ermöglichen.

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 in allen Browsern und auf allen Plattformen garantiert ist. Achten Sie darauf, 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 Looker-Kontext 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 erstellt, über die eine dashboard:run-Nachricht an das Dashboard gesendet wird.

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 SDK-Demo einbetten.

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

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

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

  1. Installieren Sie Node.js, falls noch nicht geschehen.
  2. Laden Sie das Repository /looker-open-source/embed-sdk herunter oder klonen Sie es.
  3. Rufen Sie in einem Terminalfenster das Verzeichnis /embed-sdk auf 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 dem Endpunkt auf Ihrem Server, an dem eine Authentifizierung durchgeführt wird. Sie werden für alle eingebetteten Inhalte verwendet.

Geben Sie die Portnummer an, wenn sie zum Aufrufen des Looker-Servers über Browser-Clients erforderlich ist. Beispiel: looker.example.com:443

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

Anschließend wird der eingebettete Inhalt mithilfe einer Reihe von Schritten zur Definition seiner Parameter erstellt. Einige dieser Parameter sind optional, andere sind obligatorisch.

Der Prozess beginnt mit dem Erstellen des Builders mit einem Dashboard-id oder einem url-Objekt, das auf ein Dashboard verweist, das durch den auf der Seite Einbettung von Einmalanmeldung (SSO) beschriebenen Prozess erstellt wurde.

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 Looker-Einbettungs-UI in einem HTML-Element mit dem ID-Wert dashboard platziert:

.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 zum eingebetteten Inhalt herstellen

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

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

URLs für das SDK erstellen

Die Hauptdokumentation für URLs zum Einbetten von Looker-SSO finden Sie auf der Dokumentationsseite zur Einmalanmeldung (SSO). Der einzige Unterschied beim Erstellen von URLs für das SDK ist, dass du einen sdk=2-Parameter neben anderen Parametern wie Filtern oder dem Parameter embed_domain zur Einbettungs-URL hinzufü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 er Teil der signierten SSO-URL ist.

Auth-Endpunkt

Da das Einbettungsgeheimnis sorgfältig geprüft werden muss, können eingebettete SSO-URLs nicht im Browser erstellt werden. Um den Prozess einfacher und sicherer zu machen, können Sie stattdessen Folgendes tun:

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

Wenn angegeben, wird bei der Erstellung eines Einbettungselements mit einer ID 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, die zum Erstellen des eingebetteten Inhalts verwendet 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
  })

Knotenassistent

In server_utils/auth_utils.ts ist eine Signierhilfemethode 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 });
});

Dies 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 Einbettungs-URL erforderlich.

Fehlerbehebung

Logging

Das Embed SDK basiert auf Chatty. Chatty verwendet für das Logging 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 = ''