Introduzione all'SDK Embed

L'SDK Embed di Looker è una libreria di funzioni che puoi aggiungere al codice della tua applicazione web basata su browser per gestire dashboard, Look, report ed esplorazioni incorporate nella tua app web.

L'SDK Embed facilita l'incorporamento nei modi seguenti:

• Fornisce l'incapsulamento del contenuto incorporato senza necessità di creare manualmente gli elementi HTML.
• Fornisce comunicazione point-to-point evitando quindi la comunicazione 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 di Looker incorporati utilizzando eventi JavaScript come dashboard:run:start o page:changed, descritti nella pagina della documentazione Eventi JavaScript incorporati. Gli sviluppatori che incorporano contenuti di 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 insieme alla tua istanza Looker ed esegue comandi sul server Looker.
• Gli SDK client dell'API Looker risiedono nel codice delle applicazioni non basate su browser per fornire 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. Assicurati di scrivere il codice JavaScript in modo da tenere conto della gestione degli eventi dei diversi browser.

Esempio rapido

In questo esempio, viene creata una dashboard con ID 11 all'interno di un elemento DOM con ID embed_container. Gli eventi dashboard:run:start e dashboard:run:complete vengono utilizzati per aggiornare lo stato dell'interfaccia utente della finestra di incorporamento, mentre un pulsante con ID run viene associato a uno script per l'invio di un messaggio dashboard:run alla dashboard.

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

Un esempio più completo è descritto nella pagina della documentazione Embed SDK demo (Demo dell'SDK Embed).

Configurazione dell'SDK di incorporamento di Looker

L'SDK Embed di Looker utilizza un pattern di interfaccia fluida. Dopo aver installato l'SDK Embed, crea i contenuti incorporati e connettiti ai contenuti incorporati. Una volta stabilita la connessione, l'applicazione di hosting può interagire con i contenuti incorporati.

Installazione dell'SDK Embed

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

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

1. Installa Node.js, se non lo 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

Per prima cosa, inizializza l'SDK con l'indirizzo del server di Looker e l'endpoint del server dell'applicazione di incorporamento che creerà un URL di accesso incorporato di Looker firmato. Questi server vengono utilizzati da tutti i contenuti incorporati. Per l'inserimento privato, ometti l'endpoint di firma.

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

I contenuti incorporati vengono poi creati seguendo una serie di passaggi per definirne i parametri. Alcuni di questi parametri sono facoltativi, mentre altri sono obbligatori.

Il processo inizia con la creazione del generatore con una dashboard id o con un url che fa riferimento a una dashboard (creata tramite la procedura descritta nella pagina della documentazione relativa all'embedding firmato).

getEmbedSDK().createDashboardWithId('id')

o

getEmbedSDK().createDashboardWithUrl('url')

A questo punto, puoi aggiungere altri attributi al generatore per completare la configurazione.

Ad esempio, puoi specificare dove inserire l'interfaccia utente di incorporamento di Looker nella pagina web. La chiamata seguente inserisce l'interfaccia utente di incorporamento di Looker in un elemento HTML con un valore ID di dashboard:

.appendTo('#dashboard')

Aggiungi gestori di eventi:

.on('dashboard:run:start',
  () => updateStatus('Running')
)
.on('dashboard:run:complete',
  () => updateStatus('Done')
)

Crea un client incorporato chiamando il metodo di compilazione:

.build()

Connessione ai contenuti incorporati

Una volta creato il client, chiama connect per creare l'iframe. Il processo di connessione crea l'attributo src utilizzato per l'iframe effettivo. Il modo in cui viene generato il valore src si basa sul modo in cui viene inizializzato l'SDK Embed:

1. Firmato: viene chiamato l'endpoint specificato dal secondo argomento della chiamata init. L'endpoint dovrebbe restituire un URL di accesso all'embed firmato.
2. Senza cookie: viene chiamato l'endpoint o la funzione specificata dal secondo argomento della chiamata initCookieless. L'endpoint o la funzione dovrebbe restituire token senza cookie, in particolare i token di autenticazione e navigazione. I token vengono aggiunti all'URL di accesso all'embed.
3. Privata: la connessione di incorporamento è privata se non viene fornito il secondo argomento della chiamata init. In questo caso, l'URL viene ricavato dal builder e decorato con i parametri necessari per l'incorporamento di Looker. Per l'embed privato, è previsto che l'utente abbia già eseguito l'accesso a Looker o che l'URL di incorporamento includa il parametro allow_login_screen=true.

connect restituisce un Promise che risolve nell'interfaccia di connessione per l'iframe incorporato.

  .connect()
  .then((connection) => {
    // Save the connection
  })
  .catch(console.error)

Interazione

L'SDK Embed 2.0.0 restituisce una connessione unificata che supporta l'interazione con tutti i tipi di contenuti di Looker. L'applicazione di incorporamento può determinare il tipo di contenuti visualizzati e interagire di conseguenza.

if (connection.getPageType() === 'dashboards') {
  connection.asDashboardConnection().run()
} else (connection.getPageType() === 'looks') {
  connection.asLookConnection().run()
} else (connection.getPageType() === 'explore') {
  connection.asExploreConnection().run()
}

L'iframe non deve essere ricreato quando è necessario caricare contenuti diversi. È invece possibile utilizzare i metodi di connessione loadDashboard, loadLook, loadExplore o loadUrl. I metodi loadDashboard, loadLook e loadExplore accettano un id. Il metodo loadUrl accetta un URL incorporato e può essere utilizzato per specificare parametri aggiuntivi (ad esempio i filtri).

connection.loadDashboard('42')
// OR
connection.loadUrl('/embed/dashboards/42?state=california')

Se è necessario creare un nuovo iframe, l'SDK Embed non chiamerà di nuovo gli endpoint di sessione di firma o acquisizione. ma verrà costruito l'iframe src direttamente dal generatore. Se è necessario creare una nuova sessione di incorporamento, l'SDK Embed dovrà essere reinizializzato nel seguente modo:

getEmbedSDK(new LookerEmbedExSDK()).init('looker.example.com', '/auth')

Endpoint di autenticazione URL firmato

Questa sezione non si applica all'embedding senza cookie. Per maggiori dettagli, consulta Inserimenti senza cookie.

Per utilizzare l'SDK di incorporamento, devi fornire un servizio di backend che gestisca la firma dell'URL di incorporamento. Questo servizio viene chiamato dall'SDK di incorporamento per generare un URL firmato univoco per l'utente che effettua la richiesta. Il processo di backend può generare l'URL di incorporamento firmato utilizzando un segreto di incorporamento oppure può generare l'URL chiamando l'API Looker Create Signed Embed URL. La generazione e la firma manuali degli URL evitano di chiamare l'API Looker, il che riduce la latenza. La chiamata all'API Looker richiede meno codice ed è più facile da gestire.

Un esempio JavaScript di un metodo di assistenza che genera un URL firmato, createSignedUrl(), è disponibile in server/utils/auth_utils.ts. Viene utilizzato nel seguente modo:

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

Consulta l'esempio Python nel repository.

Configurazione dell'autenticazione avanzata dell'URL firmato

Questa sezione non si applica all'embedding senza cookie. Per maggiori dettagli, consulta Inserimenti senza cookie.

Puoi configurare l'endpoint di autenticazione in modo da consentire intestazioni delle richieste personalizzate e il supporto CORS passando un oggetto options al metodo init.

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

Risoluzione dei problemi

L'SDK Embed è basato su chatty. Chatty utilizza debug per il logging. Puoi attivare 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 = ''