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. SDK 1.8.x hat eine Reihe von Klassen exportiert. SDK 2.0.0 ersetzt diese Klassen durch Schnittstellen, die als veraltet markiert sind (alternative Schnittstellen werden 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. Das Embed SDK 2.0.0 enthält die folgenden wichtigen Änderungen:

• Für die Navigation 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 innerhalb des Looker-iFrame zu navigieren.
• connect gibt jetzt eine einheitliche Verbindung zurück und keine Verbindung, die nur mit einem Dashboard, einem Look oder einem Explore verknüpft ist. Mit der einheitlichen Verbindung können Einbettungsanwendungen erkennen, wenn ein Nutzer innerhalb des iFrame navigiert.
• Die Unterstützung für zusätzliche eingebettete Looker-Inhalte wurde für Looker-Berichte und Abfragevisualisierungen hinzugefügt.

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.

Hinweis: Looker-Berichte sind verfügbar, wenn die Funktion „Looker-Berichte“ aktiviert ist. Berichte können mit der Methode für signierte Einbettungen, der Methode für Einbettungen ohne Cookies oder der Methode für private Einbettungen eingebettet werden. Weitere Informationen finden Sie unter Looker-Berichte einbetten.

Das Embed SDK erleichtert das Einbetten auf folgende Weise:

• Es bietet die Kapselung der eingebetteten Inhalte, ohne dass HTML-Elemente manuell erstellt werden müssen.
• Es bietet eine Punkt-zu-Punkt-Kommunikation, sodass keine frameübergreifende Kommunikation stattfindet. Das Embed SDK verarbeitet die domänenübergreifende Nachrichtenübergabe zwischen Ihrer Host-Webseite und Ihren eingebetteten Looker-Inhalten über einen dedizierten Nachrichtenkanal.

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, die auf der Dokumentationsseite Eingebettete JavaScript-Ereignisse beschrieben werden. Entwickler, die Looker-Inhalte mit JavaScript-Ereignissen einbetten, müssen die HTML-Elemente erstellen, in denen die eingebetteten Inhalte untergebracht werden, und sich auf Window-Broadcast-Ereignisse für die Kommunikation zwischen der Webanwendung 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.

Looker hat keinen Einfluss auf die Reihenfolge, in der Browser Ereignisse an Webanwendungen senden. Daher ist die Reihenfolge der Ereignisse nicht browser- oder plattformübergreifend garantiert. Sie müssen Ihr JavaScript entsprechend schreiben, um die Ereignisverarbeitung verschiedener Browser zu berücksichtigen.

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 UI des Einbettungsfensters zu aktualisieren. Ein Button mit der ID run wird so programmiert, dass er eine dashboard:run-Nachricht an das Dashboard sendet.

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 ausführlicheres Beispiel finden Sie auf der Dokumentationsseite zur 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 ihnen her. Die Hostanwendung kann mit den eingebetteten Inhalten interagieren, sobald die Verbindung hergestellt ist.

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 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 ü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

Eingebettete Inhalte erstellen

Initialisieren Sie zuerst das SDK mit der Adresse des Looker-Servers und dem Endpunkt des Einbettungsanwendungsservers, der eine signierte Looker-Einbettungs-URL für die Anmeldung erstellt. Diese Server werden für alle eingebetteten Inhalte verwendet. Lassen Sie für private Einbettungen den Signierungsendpunkt 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 mehreren Schritten erstellt, um ihre Parameter zu definieren. Einige dieser Parameter sind optional, andere sind obligatorisch.

Der Prozess beginnt mit dem Erstellen des Builders entweder mit einem Dashboard id oder mit einer url, die auf ein Dashboard verweist (erstellt durch den Prozess, der auf der Dokumentationsseite Signierte Einbettung 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 dem Embed SDK 2.0.0 sowohl für signierte als auch für Einbettungen ohne Cookies verwendet werden. Vor dem Embed SDK 2.0.0 unterstützte die Einbettung ohne Cookies nur create[ContentType]WithId.

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 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 den eingebetteten Inhalten herstellen

Rufen Sie nach dem Erstellen des Clients connect auf, um den iFrame zu erstellen. Beim Verbindungsprozess 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 muss eine signierte Einbettungs-URL für die Anmeldung zurückgeben.
2. Ohne Cookies: Der Endpunkt oder die Funktion, der bzw. die durch das zweite Argument des initCookieless-Aufrufs angegeben wird, wird aufgerufen. Der Endpunkt oder die Funktion muss Token ohne Cookies zurückgeben, insbesondere die Authentifizierungs- und Navigationstoken. Die Token werden an die Einbettungs-URL für die Anmeldung 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 Looker-Einbettung erforderlich sind. Bei der privaten Einbettung wird erwartet, 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 den eingebetteten 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 Einbettungsanwendung kann ermitteln, welche Art von Inhalt angezeigt wird, und entsprechend interagieren.

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 eine id. Die Methode loadUrl akzeptiert eine Einbettungs-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 neuer iFrame erstellt werden muss, ruft das Embed SDK die Endpunkte für die Signierung oder den Sitzungserwerb nicht noch einmal auf. Stattdessen wird src des iFrame direkt aus dem 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 signierter URL

Dieser Abschnitt gilt nicht für Einbettungen ohne Cookies. Weitere Informationen finden Sie unter Einbettung ohne Cookies.

Um das Embed SDK zu verwenden, müssen Sie einen Backend-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 Back-End-Prozess kann die signierte Einbettungs-URL entweder selbst mit einem Einbettungs-Secret generieren oder die URL generieren, indem er die Looker API zum Erstellen einer signierten Einbettungs-URL aufruft. Durch die manuelle URL-Generierung und -Signierung wird der Aufruf der Looker API vermieden, was die Latenz verringert. Der Aufruf der Looker API erfordert weniger Code und ist einfacher zu verwalten.

Ein JavaScript-Beispiel für eine Hilfsmethode, die eine signierte URL generiert, createSignedUrl(), finden Sie unter server/utils/auth_utils.ts. Sie wird auf folgende Weise 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 })
})

Ein Python-Beispiel finden Sie im Repository.

Erweiterte Authentifizierungskonfiguration für signierte URLs

Dieser Abschnitt gilt nicht für Einbettungen ohne Cookies. Weitere Informationen finden Sie unter Einbettung ohne Cookies.

Sie können den Authentifizierungsendpunkt so konfigurieren, dass benutzerdefinierte Anfrageheader und CORS-Unterstützung zugelassen werden, indem Sie ein Options-Objekt an die Methode init ü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. Sie können die Protokollierung in einer Browserkonsole mit diesem Befehl 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 = ''