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 erleichtert das Einbetten auf folgende Weise:

Sie bieten die Kapselung des eingebetteten Inhalts, ohne dass HTML-Elemente manuell erstellt werden müssen.
Es wird eine Punkt-zu-Punkt-Kommunikation bereitgestellt, damit es keine frameübergreifende Kommunikation gibt. Das Embed SDK verarbeitet die domainübergreifende Nachrichtenweitergabe zwischen Ihrer Hostwebseite und Ihren eingebetteten Looker-Inhalten. Dabei wird ein spezieller Nachrichtenkanal genutzt.

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 für die Kommunikation zwischen der Web-App und den eingebetteten Inhalten auf Fenster-Broadcast-Ereignisse verlassen.

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

Das Looker Embed SDK ist im clientseitigen Code Ihrer Webanwendung enthalten und verwaltet den Einbettungskontext und den Inhalt von Looker. (Das Embed SDK bietet keinen Zugriff auf die Looker API.)
Die Looker API befindet sich auf dem Server, auf dem sich Ihre Looker-Instanz befindet, 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 nicht die Reihenfolge bestimmt, in der Browser Ereignisse an Webanwendungen senden. Das bedeutet, dass die Reihenfolge der Ereignisse in verschiedenen Browsern oder Plattformen nicht garantiert ist. Achten Sie darauf, dass Ihr JavaScript-Code korrekt geschrieben ist, um die Verarbeitung von Ereignissen in verschiedenen Browsern zu berücksichtigen.

Kurzes Beispiel

In diesem Beispiel wird ein Looker-Einbettungskontext erstellt und in ein DOM-Element mit der ID dashboard eingefügt. Anschließend wird ein Dashboard mit der ID 11 im Looker-Einbettungskontext angezeigt. Die Ereignisse dashboard:run:start und dashboard:run:complete werden verwendet, um den Status der Benutzeroberfläche des Einbettungsfensters zu aktualisieren, und über eine Schaltfläche mit der ID run wird per Script eine dashboard:run-Nachricht an das Dashboard gesendet.

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 findest du auf der Dokumentationsseite Embed SDK Demo (SDK-Demo einbetten).

Looker Embed SDK einrichten

Das Looker Embed SDK verwendet ein fließendes Schnittstellenmuster. Nach der Installation des Embed SDK erstellen Sie die eingebetteten Inhalte und stellen eine Verbindung zu den eingebetteten Inhalten her.

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 sich jedoch 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 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.
Gehen 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, der die Authentifizierung durchführt. Sie werden von allen eingebetteten Inhalten verwendet.

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

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

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

Der Prozess beginnt damit, dass der Builder entweder mit einem Dashboard-id oder mit einem url erstellt wird, der auf ein Dashboard verweist. Dieses wird durch den Prozess erstellt, der auf der Dokumentationsseite Signierte Einbettung beschrieben wird.

LookerEmbedSDK.createDashboardWithId(id)

oder

LookerEmbedSDK.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-Benutzeroberfläche eingefügt werden soll. Mit dem folgenden Aufruf wird die Einbettungsbenutzeroberfläche von Looker 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 Abschluss erstellen Sie das eingebettete Element:

.build()

Verbindung zu eingebetteten Inhalten herstellen

Wenn Sie Nachrichten an das eingebettete Element senden und von diesem empfangen möchten, müssen Sie connect() aufrufen. Dadurch wird ein Promise zurückgegeben, das zur Kommunikationsschnittstelle des angegebenen Elements aufgelöst wird:

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

URLs für das SDK erstellen

Die Hauptdokumentation für von Looker signierte Einbettungs-URLs finden Sie auf der Dokumentationsseite Signierte Einbettungen. Der einzige Unterschied beim Erstellen von URLs für das SDK besteht darin, dass du der eingebetteten URL neben anderen Parametern wie Filtern und dem Parameter embed_domain einen sdk=2-Parameter 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 Einbettungs-URL ist.

Authentifizierungsendpunkt

Da das Einbettungs-Secret sorgfältig geschützt werden muss, können signierte Einbettungs-URLs im Browser nicht erstellt werden. Um den Prozess einfacher und sicherer zu gestalten, können Sie stattdessen die folgenden Schritte ausführen:

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

Wenn dieses Flag angegeben ist und ein eingebettetes Element nur mit einer ID erstellt wird, wird seine Einbettungs-URL anhand des Elementtyps, des bereitgestellten Looker-Hosts und aller bereitgestellten Parameter generiert. Beispiel:

LookerEmbedSDK.init('looker.example.com', '/looker_auth')
LookerEmbedSDK.createcreateDashboardWithId(11)
  .build()

Im vorherigen Beispiel wird der Endpunkt /looker_auth aufgerufen und eine signierte Einbettungs-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 Authentifizierungsendpunkt kann weiter konfiguriert werden, um benutzerdefinierte Anfrageheader sowie CORS-Unterstützung zuzulassen. Übergeben Sie dazu 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
  })

Knoten-Hilfsprogramm

In server_utils/auth_utils.ts ist die Signierhilfemethode createSignedUrl() verfügbar. Sie wird so verwendet:

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 Nutzerdatenstruktur:

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