Das Embed SDK von Looker ist eine Bibliothek mit Funktionen, die Sie dem Code Ihrer browserbasierten Webanwendung hinzufügen können, um eingebettete Dashboards, Looks, Berichte und Explores in Ihrer Webanwendung zu verwalten.
Das Embed SDK bietet folgende Vorteile:
- Die eingebetteten Inhalte werden gekapselt, ohne dass HTML-Elemente manuell erstellt werden müssen.
- Point-to-Point-Kommunikation, damit keine Frame-übergreifende Kommunikation stattfindet. Das Embed SDK verarbeitet die domänenübergreifende Nachrichtenweitergabe zwischen Ihrer Host-Webseite und Ihren eingebetteten Looker-Inhalten mithilfe eines speziellen Nachrichtenkanals.
Ohne das Embed SDK können Sie Ereignisse in eingebetteten Looker-Inhalten aufrufen oder darauf reagieren, indem Sie JavaScript-Ereignisse wie dashboard:run:start oder page:changed verwenden. Diese werden auf der Dokumentationsseite Eingebettete JavaScript-Ereignisse beschrieben. Entwickler, die Looker-Inhalte mit JavaScript-Ereignissen einbetten, müssen die HTML-Elemente zum Speichern der eingebetteten Inhalte erstellen und für die Kommunikation zwischen der Webanwendung und den eingebetteten Inhalten auf Fenster-Broadcast-Ereignisse zurückgreifen.
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-Einbettungskontext und -Inhalt. Das Embed SDK bietet keinen Zugriff auf die Looker API.
- Die Looker API befindet sich auf dem Server Ihrer Looker-Instanz und führt Befehle auf dem Looker-Server aus.
- Looker API-Client-SDKs befinden sich im Code von Anwendungen, die nicht im Browser ausgeführt werden, um Zugriff auf Looker API-Funktionen zu ermöglichen.
Die Reihenfolge, in der Browser Ereignisse an Webanwendungen senden, wird nicht von Looker gesteuert. Das bedeutet, dass die Reihenfolge der Ereignisse nicht plattform- oder browserübergreifend garantiert ist. Achten Sie darauf, Ihr JavaScript so zu schreiben, dass die Ereignisbehandlung in verschiedenen Browsern berücksichtigt wird.
Kurzes Beispiel
In diesem Beispiel wird ein Dashboard mit der ID 11 in einem DOM-Element mit der ID embed_container erstellt. Mit den Ereignissen dashboard:run:start und dashboard:run:complete wird der Status der Benutzeroberfläche des Einbettungsfensters aktualisiert. Eine Schaltfläche mit der ID run ist so programmiert, dass eine dashboard:run-Nachricht an das Dashboard gesendet wird.
getEmbedSDK().init('looker.example.com', '/auth')
const setupConnection = (connection) => {
document.querySelector('#run').addEventListener('click', () => {
connection.asDashboardConnection().run()
})
}
try {
connection = await getEmbedSDK()
.createDashboardWithId('11')
.appendTo('#embed_container')
.on('dashboard:run:start', () => updateStatus('Running'))
.on('dashboard:run:complete', () => updateStatus('Done'))
.build()
.connect()
setupConnection(connection)
} catch (error) {
console.error('An unexpected error occurred', error)
}
Ein vollständigeres Beispiel findest du auf der Dokumentationsseite Embed SDK-Demo.
Looker Embed SDK einrichten
Das Looker Embed SDK verwendet ein Fluent-Interface-Muster. Nachdem du das Embed SDK installiert hast, kannst du die eingebetteten Inhalte erstellen und eine Verbindung zu den eingebetteten Inhalten herstellen. Die Hosting-Anwendung kann nach der Verbindungsherstellung mit den eingebetteten Inhalten interagieren.
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 herunterladen. Wenn Sie jedoch den Beispielcode oder die Demo sehen möchten, sollten Sie stattdessen das Looker Embed SDK-Repository verwenden.
So installieren Sie das Looker Embed SDK mit dem Looker Embed SDK-Repository:
- Installieren Sie Node.js, falls noch nicht geschehen.
- Laden Sie das
/looker-open-source/embed-sdk-Repository herunter oder klonen Sie es. - Rufen Sie in einem Terminalfenster das Verzeichnis
/embed-sdkauf und führen Sie die folgenden Befehle aus:
npm install
npm start
Eingebettete Inhalte erstellen
Initialisieren Sie zuerst das SDK mit der Adresse des Looker-Servers und dem Endpunkt des Einbettungsserver, der eine signierte Looker-Einbettungs-Anmelde-URL erstellt. Diese Server werden von allen eingebetteten Inhalten verwendet. Lassen Sie den Signaturendpunkt bei der privaten Einbettung weg.
getEmbedSDK().init('looker.example.com', '/auth')
Anschließend werden die eingebetteten Inhalte in mehreren Schritten erstellt, um ihre Parameter zu definieren. Einige dieser Parameter sind optional, andere obligatorisch.
Zuerst wird der Builder erstellt, entweder mit einem Dashboard id oder mit einem url, das auf ein Dashboard verweist, das mit dem auf der Dokumentationsseite Signierte Einbettung beschriebenen Verfahren erstellt wurde.
getEmbedSDK().createDashboardWithId('id')
oder
getEmbedSDK().createDashboardWithUrl('url')
Sie können dem Builder dann 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-Benutzeroberfläche in ein HTML-Element mit der ID dashboard eingebettet:
.appendTo('#dashboard')
Fügen Sie Event-Handler hinzu:
.on('dashboard:run:start',
() => updateStatus('Running')
)
.on('dashboard:run:complete',
() => updateStatus('Done')
)
Erstellen Sie einen eingebetteten Client, indem Sie die Build-Methode aufrufen:
.build()
Verbindung zum eingebetteten Inhalt herstellen
Rufe nach dem Erstellen des Clients connect auf, um den Iframe zu erstellen. Beim Verbindungsaufbau wird das Attribut src erstellt, das für den eigentlichen iFrame verwendet wird. Wie der Wert für src generiert wird, hängt davon ab, wie das eingebettete SDK initialisiert wird:
- Signiert: Der Endpunkt, der durch das zweite Argument des
init-Aufrufs angegeben wird, wird aufgerufen. Der Endpunkt sollte eine signierte Anmelde-URL für das Einbetten zurückgeben. - Ohne Cookies: Der Endpunkt oder die Funktion, die durch das zweite Argument des
initCookieless-Aufrufs angegeben wird, wird aufgerufen. Der Endpunkt oder die Funktion sollte Token ohne Cookies zurückgeben, insbesondere die Authentifizierungs- und Navigations-Token. Die Tokens werden an die Anmelde-URL für die Einbettung angehängt. - Privat: Die Einbettungsverbindung ist privat, wenn das zweite Argument des
init-Aufrufs nicht angegeben wird. In diesem Fall wird die URL aus dem Builder abgeleitet und mit den Parametern versehen, die für das Einbetten von Looker erforderlich sind. Bei der privaten Einbettung wird davon ausgegangen, dass der Nutzer bereits in Looker angemeldet ist oder dass die Einbettungs-URL den Parameterallow_login_screen=trueenthält.
connect gibt einen Promise zurück, der auf die Verbindungsoberfläche für den eingebetteten iframe verweist.
.connect()
.then((connection) => {
// Save the connection
})
.catch(console.error)
Interagieren
Das Embed SDK 2.0.0 gibt eine einheitliche Verbindung zurück, die die Interaktion mit allen Looker-Inhaltstypen unterstützt. Die Anwendung, in die eingebettet wird, kann bestimmen, welche Art von Inhalten angezeigt wird, und entsprechend reagieren.
if (connection.getPageType() === 'dashboards') {
connection.asDashboardConnection().run()
} else (connection.getPageType() === 'looks') {
connection.asLookConnection().run()
} else (connection.getPageType() === 'explore') {
connection.asExploreConnection().run()
}
Der iFrame muss nicht neu erstellt werden, wenn andere Inhalte geladen werden müssen. Stattdessen können die Verbindungsmethoden loadDashboard, loadLook, loadExplore oder loadUrl verwendet werden. Die Methoden loadDashboard, loadLook und loadExplore akzeptieren ein id. Die Methode loadUrl akzeptiert ein eingebettetes URL. Mit dieser Methode können zusätzliche Parameter wie Filter angegeben werden.
connection.loadDashboard('42')
// OR
connection.loadUrl('/embed/dashboards/42?state=california')
Wenn ein neuer Iframe erstellt werden muss, ruft das Embed SDK die Endpunkte für die Signatur oder Sitzung nicht noch einmal auf. Stattdessen wird der iframe src direkt über den Builder erstellt. Wenn eine neue Einbettungssitzung erstellt werden muss, muss das Embed SDK auf folgende Weise neu initialisiert werden:
getEmbedSDK(new LookerEmbedExSDK()).init('looker.example.com', '/auth')
Endpunkt für die Authentifizierung mit signierten URLs
Dieser Abschnitt gilt nicht für das Einbetten ohne Cookies. Weitere Informationen finden Sie unter Embedding ohne Cookies.
Wenn Sie das Embed SDK verwenden möchten, müssen Sie einen Back-End-Dienst angeben, der die Signatur der Einbettungs-URL übernimmt. Dieser Dienst wird vom Embed SDK aufgerufen, um eine signierte URL zu generieren, die für den anfragenden Nutzer eindeutig ist. Der Backend-Prozess kann die signierte Einbettungs-URL entweder selbst mit einem Einbettungs-Secret generieren oder die URL durch Aufrufen der Looker Create Signed Embed URL API generieren. Durch die manuelle URL-Generierung und ‑Signatur wird der Aufruf der Looker API vermieden, wodurch die Latenz verringert wird. Der Aufruf der Looker API erfordert weniger Code und ist einfacher zu verwalten.
Ein JavaScript-Beispiel für eine Hilfsmethode, die eine signierte URL (createSignedUrl()) generiert, findest du unter server/utils/auth_utils.ts. Sie wird so verwendet:
import { createSignedUrl } from './utils/auth_utils'
app.get('/looker_auth', function (req, res) {
// It is assumed that the request is authorized
const src = req.query.src
const host = 'looker.example.com'
const secret = ... // Embed secret from Looker Server Embed Admin page
const user = ... // Embedded user definition
const url = createSignedUrl(src, user, host, secret)
res.json({ url })
})
Python-Beispiel im Repository ansehen
Erweiterte Authentifizierungskonfiguration für signierte URLs
Dieser Abschnitt gilt nicht für das Einbetten ohne Cookies. Weitere Informationen finden Sie unter Embedding ohne Cookies.
Du kannst den Authentifizierungsendpunkt so konfigurieren, dass benutzerdefinierte Anfrageheader und CORS-Unterstützung zulässig sind. Dazu musst du der init-Methode ein Optionsobjekt übergeben.
getEmbedSDK().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
})
Fehlerbehebung
Das Embed SDK basiert auf chatty. Chatty verwendet debug für die Protokollierung. Mit diesem Befehl können Sie die Protokollierung 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 = ''