Introduzione all'SDK Embed

Nota:questa pagina è un riferimento per l'SDK Embed 2.0.0. Sebbene l'API 2.0.0 sia compatibile con le versioni precedenti dell'SDK Embed 1.8.x, l'implementazione sottostante è cambiata per alcune funzionalità. L'SDK 1.8.x ha esportato un numero di classi. L'SDK 2.0.0 sostituisce queste classi con interfacce contrassegnate come deprecate (sono identificate interfacce alternative). Consigliamo alle applicazioni di utilizzare le interfacce con il prefisso "I" (le interfacce con prefissi sono identiche a quelle senza). Le applicazioni di cui è stato eseguito l'upgrade all'SDK 2.0.0 dovrebbero continuare a funzionare e a comportarsi come prima. Per sfruttare i miglioramenti dell'API, sarà necessario eseguire il refactoring. Le seguenti modifiche principali sono incluse nell'SDK Embed 2.0.0:

• La navigazione tra dashboard, esplorazioni e Look non richiede più la ricreazione di un iframe. In alternativa, è 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 ulteriori contenuti incorporati di Looker per i report e le visualizzazioni delle query di Looker.

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 Explore incorporati nella tua app web.

Nota :i report di Looker sono disponibili quando la funzionalità Report di Looker è attivata. 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, vedi Incorporare 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 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 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 l'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

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 (Demo dell'SDK Embed).

Configurazione dell'SDK incorporato di Looker

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

Installazione dell'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 Looker Embed.

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

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

Costruzione dei contenuti incorporati

Per prima cosa, 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')

I contenuti incorporati vengono quindi creati utilizzando 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 tramite un dashboard id o un url che fa riferimento a un dashboard (creato dalla procedura descritta nella pagina di documentazione 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 con l'incorporamento con accesso e 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 in quale punto della pagina web inserire l'interfaccia utente di incorporamento di Looker. La seguente chiamata inserisce l'interfaccia utente 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 creazione:

.build()

Connessione ai contenuti incorporati in corso…

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 di 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 deve restituire token senza cookie, in particolare i token di autenticazione e navigazione. I token vengono aggiunti all'URL di accesso incorporato.
3. Privata: la connessione di incorporamento è privata se il secondo argomento della chiamata init non viene fornito. 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 un 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 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. In alternativa, è 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 incorporamento URL e può essere utilizzato per specificare parametri aggiuntivi (come 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 firma o di acquisizione della sessione. ma costruirà l'iframe src direttamente dal builder. Se è necessario creare una nuova sessione di incorporamento, l'SDK Embed deve essere reinizializzato nel seguente modo:

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

Endpoint di autenticazione URL firmato

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

Per utilizzare l'SDK incorporato, devi fornire un servizio di backend che gestisca la firma dell'URL di incorporamento. Questo servizio viene chiamato dall'SDK incorporato 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 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 helper che genera un URL firmato, createSignedUrl(), è disponibile in server/utils/auth_utils.ts. Viene utilizzata 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 di Python nel repository.

Configurazione avanzata dell'autenticazione con 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 intestazioni delle richieste personalizzate e il supporto di 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 si basa su chatty. Chatty utilizza debug per la registrazione. Puoi attivare la registrazione 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 = ''