Einführung in das Embed SDK

Hinweis:Diese Seite ist eine Referenz für das Embed SDK 2.0.0. Die 2.0.0-API ist zwar abwärtskompatibel mit dem Embed SDK 1.8.x, die zugrunde liegende Implementierung hat sich jedoch für einige Funktionen geändert. Mit SDK 1.8.x wurde eine Reihe von Klassen exportiert. Im SDK 2.0.0 werden diese Klassen durch Schnittstellen ersetzt, die als veraltet gekennzeichnet sind (alternative Schnittstellen sind angegeben). Wir empfehlen, dass Anwendungen die Schnittstellen mit dem Präfix „I“ verwenden. Die Schnittstellen mit Präfix sind identisch mit den Schnittstellen ohne Präfix. Anwendungen, die auf SDK 2.0.0 aktualisiert werden, sollten weiterhin wie zuvor funktionieren. Um die API-Verbesserungen nutzen zu können, ist eine Refaktorierung erforderlich. Embed SDK 2.0.0 enthält die folgenden wichtigen Änderungen:

• Beim Wechseln zwischen Dashboards, Explores und Looks muss kein iFrame mehr neu erstellt werden. Stattdessen können die Methoden loadDashboard, loadLook, loadExplore und loadUrl verwendet werden, um im Looker-iFrame zu navigieren.
• connect gibt jetzt eine einheitliche Verbindung zurück und nicht mehr eine Verbindung, die sich nur auf ein Dashboard, einen Look oder ein Explore bezieht. Mit der einheitlichen Verbindung können eingebettete Anwendungen erkennen, wenn ein Nutzer im iFrame navigiert.
• Es wurde Unterstützung für zusätzliche eingebettete Looker-Inhalte für Looker-Berichte und Abfragevisualisierungen hinzugefügt.

Das Embed SDK von Looker ist eine Funktionsbibliothek, die Sie dem Code Ihrer browserbasierten Webanwendung hinzufügen können, um eingebettete Dashboards, Looks, Berichte und Explores in Ihrer Webanwendung zu verwalten.

Hinweis :Looker-Berichte sind verfügbar, wenn die Funktion „Looker-Berichte“ aktiviert ist. Berichte können mit der Methode zum Einbetten mit Signatur, der Methode zum Einbetten ohne Cookies oder der Methode zum privaten Einbetten eingebettet werden. Weitere Informationen finden Sie unter Looker-Berichte einbetten.

Das Embed SDK erleichtert das Einbetten auf folgende Weise:

• Sie kapselt die eingebetteten Inhalte, ohne dass HTML-Elemente manuell erstellt werden müssen.
• Bereitstellung einer Punkt-zu-Punkt-Kommunikation, sodass keine frameübergreifende Kommunikation stattfindet. Das Embed SDK übernimmt die domänenübergreifende Nachrichtenübermittlung zwischen Ihrer Host-Webseite und den eingebetteten Looker-Inhalten über einen dedizierten Nachrichtenkanal.

Ohne das Embed SDK können Sie Ereignisse in eingebetteten Looker-Inhalten mit 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 auf Window Broadcast-Ereignisse für die Kommunikation zwischen der Web-App und den eingebetteten Inhalten 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-Einbettungskontext 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.
• Looker API-Client-SDKs befinden sich im Code von Nicht-Browser-Anwendungen, um Zugriff auf Looker API-Funktionen zu ermöglichen.

Beachten Sie, dass Looker die Reihenfolge, in der Browser Ereignisse an Webanwendungen senden, nicht steuert. Das bedeutet, dass die Reihenfolge der Ereignisse nicht browser- oder plattformübergreifend garantiert ist. Achten Sie darauf, Ihr JavaScript so zu schreiben, dass die Ereignisverarbeitung verschiedener Browser 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. Die Ereignisse dashboard:run:start und dashboard:run:complete werden verwendet, um den Status der Benutzeroberfläche des Einbettungsfensters zu aktualisieren. Für eine Schaltfläche mit der ID run wird ein Skript erstellt, um eine dashboard:run-Nachricht an das Dashboard zu senden.

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 finden Sie auf der Dokumentationsseite Embed SDK-Demo.

Looker Embed SDK einrichten

Das Looker Embed SDK verwendet ein Fluent-Interface-Muster. Nachdem Sie das Embed SDK installiert haben, erstellen Sie die eingebetteten Inhalte und stellen eine Verbindung zu den eingebetteten Inhalten her. Die Hosting-Anwendung kann mit den eingebetteten Inhalten interagieren, sobald die Verbindung hergestellt wurde.

Embed SDK installieren

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

So installieren Sie das Looker Embed SDK über das Looker Embed SDK-Repository:

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

npm install
npm start

Eingebetteten Inhalt erstellen

Initialisieren Sie zuerst das SDK mit der Adresse des Looker-Servers und dem Endpunkt des Einbettungsanwendungsservers, der eine signierte Looker-Anmelde-URL für die Einbettung erstellt. Diese Server werden von allen eingebetteten Inhalten verwendet. Lassen Sie bei privatem Einbetten den Signierungs-Endpunkt weg.

Hinweis: Geben Sie die Portnummer an, wenn sie erforderlich ist, um den Looker-Server von Browserclients aus zu erreichen. Beispiel: looker.example.com:443

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

Anschließend werden die eingebetteten Inhalte in einer Reihe von Schritten erstellt, um ihre Parameter zu definieren. Einige dieser Parameter sind optional, andere sind erforderlich.

Der Prozess beginnt mit dem Erstellen des Builders entweder mit einem Dashboard id oder mit einem url, das auf ein Dashboard verweist (erstellt durch den Prozess, der auf der Dokumentationsseite Signiertes Einbetten beschrieben wird).

getEmbedSDK().createDashboardWithId('id')

oder

getEmbedSDK().createDashboardWithUrl('url')

Anschließend können Sie dem Builder weitere Attribute hinzufügen, um die Einrichtung abzuschließen.

Hinweis :Die create[ContentType]WithUrl-Funktionen können ab Embed SDK 2.0.0 sowohl mit signierten als auch mit cookielosen Einbettungen verwendet werden. Vor dem Embed SDK 2.0.0 wurde die cookieless-Einbettung nur für create[ContentType]WithId unterstützt.

Sie können beispielsweise festlegen, an welcher Stelle auf Ihrer Webseite die Looker-Einbettungs-UI eingefügt werden soll. Mit dem folgenden Aufruf wird die Looker-Einbettungs-UI in ein HTML-Element mit der ID dashboard eingefügt:

.appendTo('#dashboard')

Event-Handler hinzufügen:

.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 zu eingebetteten Inhalten herstellen

Rufen Sie nach dem Erstellen des Clients connect auf, um das iFrame zu erstellen. Beim Verbinden wird das Attribut src erstellt, das für den eigentlichen iFrame verwendet wird. Die Art und Weise, wie der src-Wert generiert wird, hängt davon ab, wie das Embed SDK initialisiert wird:

1. Signiert: Der Endpunkt, der durch das zweite Argument des init-Aufrufs angegeben wird, wird aufgerufen. Der Endpunkt sollte eine signierte Einbettungs-Anmelde-URL zurückgeben.
2. Ohne Cookie: Der Endpunkt oder die Funktion, die durch das zweite Argument des initCookieless-Aufrufs angegeben wird, wird aufgerufen. Der Endpunkt oder die Funktion sollte cookielose Tokens zurückgeben, insbesondere die Authentifizierungs- und Navigationstokens. Die Tokens werden an die Einbettungs-Anmelde-URL angehängt.
3. 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 die Einbettung von Looker erforderlich sind. Bei privaten Einbettungen wird davon ausgegangen, dass der Nutzer bereits in Looker angemeldet ist oder dass die Einbettungs-URL den Parameter allow_login_screen=true enthält.

connect gibt ein Promise zurück, das in die Verbindungsschnittstelle für das eingebettete iFrame aufgelöst wird.

  .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 einbettende Anwendung 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 unterschiedliche Inhalte geladen werden sollen. 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 (z. B. Filter) angegeben werden.

connection.loadDashboard('42')
// OR
connection.loadUrl('/embed/dashboards/42?state=california')

Wenn ein neues iFrame erstellt werden muss, ruft das Embed SDK die Endpunkte für die Signierung oder den Sitzungserwerb nicht noch einmal auf. Stattdessen wird das iFrame src direkt aus dem Builder erstellt. Sollte es erforderlich sein, eine neue Einbettungssitzung zu erstellen, muss das Embed SDK so neu initialisiert werden:

getEmbedSDK(new LookerEmbedExSDK()).init('looker.example.com', '/auth')

Signierter URL-Authentifizierungsendpunkt

Dieser Abschnitt gilt nicht für das Einbetten ohne Cookies. Weitere Informationen finden Sie unter Einbetten ohne Cookies.

Wenn Sie das Embed SDK verwenden möchten, müssen Sie einen Back-End-Dienst bereitstellen, der die Signierung 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 mithilfe eines Einbettungs-Secrets generieren oder die URL durch Aufrufen der Looker Create Signed Embed URL API generieren. Durch die manuelle URL-Generierung und ‑Signierung wird die Looker API nicht aufgerufen, was die Latenz verringert. Für den Aufruf der Looker API ist weniger Code erforderlich und sie ist einfacher zu verwalten.

Ein JavaScript-Beispiel für eine Hilfsmethode, die eine signierte URL (createSignedUrl()) generiert, finden Sie 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

Erweiterte Authentifizierungskonfiguration für signierte URLs

Dieser Abschnitt gilt nicht für das Einbetten ohne Cookies. Weitere Informationen finden Sie unter Einbetten ohne Cookies.

Sie können den Auth-Endpunkt so konfigurieren, dass benutzerdefinierte Anfrageheader und CORS-Unterstützung zugelassen werden. Dazu übergeben Sie ein Optionenobjekt an die Methode init.

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 = ''