Introduzione all'SDK Embed

L'SDK Embed di Looker è una libreria di funzioni che puoi aggiungere al codice di un'applicazione web basata su browser per gestire dashboard incorporate, Look ed Explore in un'app web. L'SDK Embed facilita l'incorporamento nei modi seguenti:

  • Forniscono l'incapsulamento del contenuto incorporato senza necessità di creare manualmente gli elementi HTML.
  • Fornire comunicazioni point-to-point per evitare comunicazioni cross-frame. L'SDK Embed gestisce la trasmissione tra domini diversi dei messaggi fra la pagina web dell'host e il contenuto Looker incorporato, utilizzando un canale di messaggistica dedicato.

Senza l'SDK Embed, puoi richiamare o rispondere agli eventi nei contenuti Looker incorporati tramite eventi JavaScript, come dashboard:run:start o page:changed, descritti nella pagina della documentazione Eventi JavaScript incorporati. Gli sviluppatori che incorporano contenuti Looker con eventi JavaScript devono creare gli elementi HTML per ospitare il contenuto incorporato e affidarsi a eventi di trasmissione della finestra per le comunicazioni tra l'app web e il contenuto incorporato.

Tieni presente che l'SDK Embed di Looker è diverso dall'API Looker e dall'SDK dell'API Looker:

  • L'SDK Embed di Looker risiede nel codice lato client dell'applicazione web e gestisce il contesto di incorporamento e il contenuto di Looker L'SDK Embed non fornisce accesso all'API Looker.
  • L'API Looker risiede sul server con la tua istanza di Looker ed esegue comandi sul server di Looker.
  • Gli SDK client dell'API Looker risiedono nel codice di applicazioni non basate su browser per offrire un facile accesso alle funzioni dell'API Looker.

Tieni presente che Looker non controlla l'ordine in cui i browser inviano gli eventi alle applicazioni web. Ciò significa che l'ordine degli eventi non è garantito per tutti i browser o le piattaforme. Verifica di scrivere il JavaScript in modo da tenere conto della gestione degli eventi dei diversi browser.

Esempio rapido

Questo esempio crea un contesto di incorporamento Looker, lo inserisce in un elemento DOM con un ID dashboard e poi visualizza una dashboard con un ID 11 nel contesto di incorporamento Looker. Gli eventi dashboard:run:start e dashboard:run:complete vengono utilizzati per aggiornare lo stato dell'interfaccia utente della finestra di incorporamento e un pulsante con ID run viene configurato in modo da inviare un messaggio dashboard:run alla dashboard.

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

Un esempio più completo è descritto nella pagina della documentazione Incorporare l'SDK demo.

Configurazione dell'SDK Embed di Looker

L'SDK Embed di Looker utilizza un pattern dell'interfaccia fluente. Una volta installata l'SDK Embed, crei il contenuto incorporato e colleghi i contenuti incorporati.

Installazione dell'SDK Embed

Puoi recuperare la libreria Embed SDK di Looker tramite il gestore di pacchetti del nodo (NPM) all'indirizzo https://www.npmjs.com/package/@looker/embed-sdk. Tuttavia, se vuoi visualizzare il codice campione o la demo, utilizza il repository dell'SDK Embed di Looker.

Per installare l'SDK Embed di Looker utilizzando il repository dell'SDK Embed di Looker:

  1. Installa Node.js, se non l'hai ancora fatto.
  2. Scarica o clona il repository /looker-open-source/embed-sdk.
  3. In una finestra del terminale, vai alla directory /embed-sdk ed esegui questi comandi:
npm install
npm start

Creazione dei contenuti incorporati

Innanzitutto, inizializza l'SDK con l'indirizzo del tuo server web e, facoltativamente, l'endpoint sul server che eseguirà l'autenticazione. Vengono utilizzati da tutti i contenuti incorporati.

Includi il numero della porta se è necessario per raggiungere il server Looker dai client del browser. Ad esempio: looker.example.com:443

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

Successivamente, i contenuti incorporati vengono generati mediante una serie di passaggi per definire i relativi parametri. Alcuni di questi parametri sono facoltativi, mentre altri sono obbligatori.

Il processo inizia con la creazione del builder con una dashboard id o un url che fa riferimento a una dashboard (creata con il processo descritto nella pagina della documentazione relativa all'incorporamento del Single Sign-On).

LookerEmbedSDK.createDashboardWithId(id)

o

LookerEmbedSDK.createDashboardWithUrl(url)

Puoi poi aggiungere altri attributi al generatore per completare la configurazione. Ad esempio, puoi specificare in quale punto della pagina web inserire la UI di incorporamento di Looker. La chiamata seguente posiziona la UI di incorporamento di Looker all'interno di un elemento HTML con valore dashboard:

.appendTo('#dashboard')

Puoi aggiungere gestori di eventi:

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

Per finire, crea l'elemento incorporato:

.build()

Collegamento ai contenuti incorporati

Se vuoi inviare e ricevere messaggi nell'elemento incorporato, devi chiamare connect(), che restituisce una promessa che si risolve nell'interfaccia di comunicazione dell'elemento:

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

Creare URL per l'SDK

La documentazione principale per gli URL di incorporamento SSO di Looker è disponibile nella pagina della documentazione Incorporamento del Single Sign-On (SSO). L'unica differenza nella creazione di URL per l'SDK è che devi aggiungere un parametro sdk=2 all'URL di incorporamento insieme ad altri parametri come i filtri e il parametro embed_domain. Questo parametro consente a Looker di determinare che l'SDK è presente e di trarre vantaggio dalle funzionalità aggiuntive fornite da quest'ultimo. Ad esempio:

/embed/looks/4?embed_domain=https://mywebsite.com&sdk=2
                                                 ^^^^^^

L'SDK non può aggiungere questo parametro stesso perché fa parte dell'URL SSO firmato.

L'endpoint di autenticazione

Poiché il secret di incorporamento deve essere protetto con attenzione, non è possibile creare URL SSO incorporati nel browser. Per semplificare e rendere più sicuro il processo, procedi come segue:

  1. Implementare una funzione di firma URL nel server web. Il server dovrebbe restituire un URL firmato utilizzando uno dei processi documentati nel repository GitHub di Esempi SSO SSO di Looker.
  2. Passa l'URL SSO incorporato a quell'endpoint di firma nell'SDK Embed. La posizione dell'endpoint è specificata dal parametro authUrl in LookerEmbedSDK.init().

Se specificato, ogni volta che un elemento di incorporamento viene creato usando solo un ID, l'URL di incorporamento viene generato utilizzando il tipo di elemento, l'host Looker fornito e tutti i parametri forniti. Ad esempio:

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

Verrà richiamato l'endpoint /looker_auth e verrà restituito un URL SSO firmato che può essere utilizzato per creare contenuti incorporati:

src=https://looker.example.com/embed/dashboards/11?sdk=2&embed_host=https://yourhost.example.com

Configurazione di autenticazione avanzata

L'endpoint di autenticazione può essere configurato ulteriormente per consentire le intestazioni delle richieste personalizzate e il supporto CORS. Puoi farlo trasmettendo un oggetto opzioni al metodo 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
  })

Assistente dei nodi

Un metodo di supporto per la firma createSignedUrl() è disponibile in server_utils/auth_utils.ts. Il suo utilizzo è il seguente:

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

Ecco la struttura dei dati utente:

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: {}
}

Il parametro access_filters è stato rimosso in Looker 3.10, ma è comunque obbligatorio con un segnaposto vuoto nell'URL di incorporamento.

Risolvere i problemi

Logging

L'SDK Embed si basa su Chat. Chatty utilizza il debug per la registrazione. Puoi abilitare il logging in una console del browser con questo comando:

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