Hinweis: Sie sehen sich die Looker-Dokumentation an. Die Looker Studio-Dokumentation finden Sie unter https://support.google.com/looker-studio.

Diese Seite wurde von der Cloud Translation API übersetzt.

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:

Die eingebetteten Inhalte werden gekapselt, ohne dass HTML-Elemente manuell erstellt werden müssen.
Point-to-Point-Kommunikation, damit keine Frame-übergreifende Kommunikation erfolgt. 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 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 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 mit 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 einfachen 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 Looker-Embed-Kontext erstellt, in ein DOM-Element mit der ID dashboard eingefügt und dann ein Dashboard mit der ID 11 im Looker-Embed-Kontext angezeigt. 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.

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

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 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.
Rufen Sie in einem Terminalfenster das Verzeichnis /embed-sdk auf 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, über den die Authentifizierung durchgeführt wird. Sie werden von allen eingebetteten Inhalten verwendet.

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

LookerEmbedSDK.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.

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

So fügen Sie Event-Handler hinzu:

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

Zum Schluss erstellen Sie das eingebettete Element:

.build()

Verbindung zu den eingebetteten Inhalten herstellen

Wenn Sie Nachrichten an das eingebettete Element senden und von ihm empfangen möchten, müssen Sie connect() aufrufen. Dadurch wird ein Promise zurückgegeben, das auf die Kommunikationsschnittstelle des jeweiligen Elements verweist:

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

URLs für das SDK erstellen

Die Hauptdokumentation zu signierten Looker-Einbettungs-URLs finden Sie auf der Dokumentationsseite Signierte Einbettung. Der einzige Unterschied beim Erstellen von URLs für das SDK besteht darin, dass der Embed-URL neben anderen Parametern wie Filtern und dem embed_domain-Parameter auch ein sdk=2-Parameter hinzugefügt werden muss. Anhand dieses Parameters kann Looker feststellen, ob das SDK vorhanden ist, und zusätzliche Funktionen nutzen, die vom SDK bereitgestellt werden. 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 Embed-URL ist.

Den Authentifizierungsendpunkt

Da das Geheime-Embedding-Attribut sorgfältig geschützt werden muss, können signierte Embed-URLs nicht im Browser erstellt werden. Sie können den Vorgang vereinfachen und sicherer machen, indem Sie stattdessen die folgenden Schritte ausführen:

Implementieren Sie eine URL-Signaturfunktion in Ihrem Webserver. Der Server sollte eine signierte URL mit einem der Prozesse zurückgeben, die im GitHub-Repository Looker Embed SSO Examples dokumentiert sind.
Übergeben Sie die signierte Einbettungs-URL an diesen Signaturendpunkt im Embed SDK. Der Speicherort des Endpunkts wird durch den Parameter authUrl in LookerEmbedSDK.init() angegeben.

Wenn diese Option angegeben ist, wird die Einbettungs-URL jedes Mal, wenn ein Einbettungselement nur mit einer ID erstellt wird, anhand des Typs des Elements, des angegebenen Looker-Hosts und aller angegebenen Parameter generiert. Beispiel:

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

Im vorherigen Beispiel wird der /looker_auth-Endpunkt aufgerufen und eine signierte Einbettungs-URL zurückgegeben, mit der die eingebetteten Inhalte erstellt werden können:

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. Dazu übergeben Sie der init-Methode ein Optionsobjekt:


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

In server_utils/auth_utils.ts wird die Signatur-Hilfsmethode createSignedUrl() bereitgestellt. So verwenden Sie es:

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 });
});

Das 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, ist aber weiterhin mit einem leeren Platzhalter in der Einbettungs-URL erforderlich.

Fehlerbehebung

Logging

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