Introduzione all'SDK Embed

Nota: questa pagina è un riferimento per l'SDK Embed 2.0.0. Sebbene l'API 2.0.0 sia retrocompatibile con l'SDK Embed 1.8.x, l'implementazione sottostante è cambiata per alcune funzionalità. L'SDK 1.8.x ha esportato una serie di classi. L'SDK 2.0.0 sostituisce queste classi con interfacce contrassegnate come obsolete (vengono identificate interfacce alternative). Ti consigliamo di utilizzare le interfacce con il prefisso "I" (le interfacce con i prefissi sono identiche a quelle senza prefissi). Le applicazioni di cui è stato eseguito l'upgrade all'SDK 2.0.0 dovrebbero continuare a funzionare e comportarsi come in precedenza. Per sfruttare i miglioramenti dell'API, sarà necessario eseguire il refactoring di alcuni elementi. L'SDK Embed 2.0.0 include le seguenti modifiche principali:

• La navigazione tra dashboard, Explore e Look non richiede più la ricreazione di un iframe. Invece, è possibile utilizzare i metodi loadDashboard, loadLook, loadExplore e loadUrl per navigare all'interno dell'iframe di Looker.
• connect ora restituisce una connessione unificata anziché una connessione correlata solo a una dashboard, un Look o un'esplorazione. La connessione unificata consente alle applicazioni di incorporamento di rilevare un utente che naviga all'interno dell'iframe.
• È stato aggiunto il supporto per altri contenuti incorporati di Looker per i report e le visualizzazioni delle query di Looker.

L'SDK Embed di Looker è una libreria di funzioni che è possibile aggiungere al codice di un'applicazione web basata su browser per gestire dashboard incorporate, Look, report ed Explore in un'app web.

Nota: i report di Looker sono disponibili quando la funzionalità dei report di Looker è abilitata. I report possono essere incorporati con il metodo di incorporamento firmato, il metodo di incorporamento senza cookie o il metodo di incorporamento privato. Per maggiori dettagli, consulta Incorporare i report di Looker.

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 nel contenuto Looker incorporato utilizzando eventi JavaScript come dashboard:run:start o page:changed, descritti nella pagina della documentazione Embedded JavaScript events (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.

È importante notare 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 offrire un facile accesso alle funzioni dell'API Looker.

È importante sapere 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

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

Configurare l'SDK Embed di Looker

L'SDK Embed di Looker utilizza un pattern di interfaccia fluida. Dopo aver installato l'SDK Embed, devi quindi creare il contenuto incorporato e connetterti a quest'ultimo. L'applicazione di hosting può interagire con il contenuto incorporato una volta stabilita la connessione.

Installare l'SDK Embed

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

Per installare l'SDK Embed di Looker utilizzando il repository dell'SDK Embed di Looker, segui questi passaggi:

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

npm install
npm start

Creare il contenuto incorporato

Innanzitutto, inizializza l'SDK con l'indirizzo del server 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'incorporamento privato, ometti l'endpoint di firma.

Nota: includi il numero di porta se è necessario per raggiungere il server Looker dai client browser. Ad esempio: looker.example.com:443

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

Il contenuto incorporato viene quindi creato utilizzando una serie di passaggi per definirne i parametri. Alcuni di questi parametri sono facoltativi, altri obbligatori.

La procedura inizia con la creazione del builder con una dashboard id o con un url che fa riferimento a una dashboard (creata dalla procedura descritta nella pagina della documentazione sull'incorporamento firmato).

getEmbedSDK().createDashboardWithId('id')

o

getEmbedSDK().createDashboardWithUrl('url')

Puoi quindi aggiungere altri attributi al builder per completare la configurazione.

Nota: Le funzioni create[ContentType]WithUrl possono essere utilizzate sia con l'incorporamento firmato sia con l'incorporamento senza cookie a partire dall'SDK Embed 2.0.0. Prima dell'SDK Embed 2.0.0, l'incorporamento senza cookie supportava solo create[ContentType]WithId.

Ad esempio, puoi specificare dove inserire la UI di incorporamento di Looker nella pagina web. La seguente chiamata inserisce la UI di incorporamento di Looker all'interno di 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 build:

.build()

Connettersi al contenuto incorporato

Una volta creato il client, chiama connect per creare l'iframe. La procedura di connessione crea l'attributo src utilizzato per l'iframe effettivo. Il modo in cui viene generato il valore src dipende da come 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 incorporato 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 incorporato.
3. Privato: la connessione di incorporamento è privata se non viene fornito il secondo argomento della chiamata init. In questo caso, l'URL viene derivato dal builder e decorato con i parametri richiesti per l'incorporamento di Looker. Per l'incorporamento 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 una Promise che si risolve nell'interfaccia di connessione per l'iframe incorporato.

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

Interagire

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 contenuto visualizzato 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()
}

Non è necessario ricreare l'iframe 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 di incorporamento e può essere utilizzato per specificare parametri aggiuntivi (ad esempio 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 firma o di acquisizione della sessione. Invece, costruirà direttamente l'iframe src dal builder. 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 dell'URL firmato

Questa sezione non si applica all'incorporamento senza cookie. Per maggiori dettagli, consulta Incorporamento senza cookie.

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

Un esempio JavaScript di un metodo helper 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 })
})

Vedi l'esempio Python nel repository.

Configurazione avanzata dell'autenticazione dell'URL firmato

Questa sezione non si applica all'incorporamento senza cookie. Per maggiori dettagli, consulta Incorporamento senza cookie.

Puoi configurare l'endpoint di autenticazione per consentire le intestazioni delle richieste personalizzate e il supporto CORS passando un oggetto di opzioni 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 = ''