Beachten Sie, dass Sie sich gerade die Looker-Dokumentation ansehen. Die Looker Studio-Dokumentation finden Sie unter https://support.google.com/looker-studio.

Einführung in das Embed SDK

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 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.
Punktgenaue Kommunikation, damit keine rahmenübergreifende Kommunikation möglich ist Das Embed SDK verarbeitet domainübergreifende Nachrichten, die zwischen der Hostwebseite und Ihren eingebetteten Looker-Inhalten übergeben werden. Dabei wird ein eigener Nachrichtenkanal verwendet.

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. Eine Beschreibung finden Sie auf der Dokumentationsseite zu eingebetteten JavaScript-Ereignissen. 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 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.
Looker API-Client-SDKs befinden sich im Code von nicht browserbasierten Anwendungen, um einen einfachen Zugriff auf Looker API-Funktionen zu ermöglichen.

Beachten Sie, dass Looker nicht die Reihenfolge steuert, in der Browser Ereignisse an Webanwendungen senden. Das bedeutet, dass die Reihenfolge der Ereignisse nicht in allen Browsern oder auf allen Plattformen garantiert ist. Achten Sie darauf, Ihren JavaScript-Code richtig zu schreiben, um die Ereignisverarbeitung verschiedener Browser zu berücksichtigen.

Kurzes Beispiel

In diesem Beispiel wird ein Looker-Einbettungskontext erstellt, in ein DOM-Element mit der ID dashboard eingefügt und anschließend 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 UI des Einbettungsfensters aktualisiert. Außerdem wird eine Schaltfläche mit der ID run angezeigt, 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 ist auf der Dokumentationsseite zum Einbetten des SDKs beschrieben.

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 Looker-Embed SDK-Bibliothek ü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 mit dem Looker Embed SDK-Repository:

Installieren Sie Node.js, falls Sie das noch nicht getan haben.
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 dem Endpunkt auf Ihrem Server, auf dem die Authentifizierung durchgeführt wird. Sie werden von allen eingebetteten Inhalten verwendet.

Geben Sie die Portnummer ein, wenn der Looker-Server über Browserclients erreicht werden muss. Beispiel: looker.example.com:443

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

Anschließend werden die eingebetteten Inhalte mithilfe mehrerer Schritte definiert, um die Parameter zu definieren. Einige dieser Parameter sind optional und andere obligatorisch.

Der Prozess beginnt mit dem Erstellen des Builders mit einem Dashboard-id oder url, das auf ein Dashboard verweist, das durch den auf der Dokumentationsseite Einmalanmeldung (SSO) erstellten Vorgang erstellt wird.

LookerEmbedSDK.createDashboardWithId(id)

oder

LookerEmbedSDK.createDashboardWithUrl(url)

Sie können dann zusätzliche Attribute in den Builder aufnehmen, um die Einrichtung abzuschließen. Sie können beispielsweise festlegen, 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 dem ID-Wert dashboard eingefügt:

.appendTo('#dashboard')

Sie können Event-Handler hinzufügen:

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

Zum Schluss erstellen Sie das eingebettete Element:

.build()

Mit eingebetteten Inhalten verbinden

Wenn Nachrichten an das eingebettete Element gesendet und von diesem empfangen werden sollen, muss connect() aufgerufen werden. Es wird ein Promise zurückgegeben, das in der Kommunikationsoberfläche des jeweiligen Elements aufgelöst wird:

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

URLs für das SDK erstellen

Die Hauptdokumentation zu den eingebetteten Looker-SSO-URLs finden Sie auf der Dokumentationsseite Einmalanmeldung (SSO). Der einzige Unterschied beim Erstellen von URLs für das SDK besteht darin, dass ein sdk=2-Parameter der Einbettungs-URL zusammen mit anderen Parametern wie Filtern und dem embed_domain-Parameter hinzugefügt werden muss. Mit diesem Parameter kann Looker feststellen, ob das SDK vorhanden ist, und zusätzliche Funktionen des SDKs 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.

Der Auth-Endpunkt

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

Implementieren Sie eine URL-Signaturfunktion auf Ihrem Webserver. Der Server sollte eine signierte URL mithilfe eines der im GitHub-Repository für Looker Embed-SSO-Beispiele dokumentierten Prozesse zurückgeben.
Übergeben Sie die eingebettete SSO-URL an den Signaturendpunkt im Embed SDK. Der Standort des Endpunkts wird durch den Parameter authUrl in LookerEmbedSDK.init() angegeben.

Wenn ein eingebettetes Element mithilfe einer ID erstellt wird, wird die zugehörige Einbettungs-URL anhand des Elementtyps, des angegebenen Looker-Hosts und der bereitgestellten Parameter 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 lässt sich weiter konfigurieren, 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 wird eine Signatur-Assistent-Methode createSignedUrl() bereitgestellt. Die Verwendung 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. Er ist jedoch noch mit einem leeren Platzhalter in der eingebetteten URL erforderlich.

Fehlerbehebung

Logging

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