Tieni presente che stai visualizzando la documentazione di Looker. Per la documentazione di Looker Studio, visita https://support.google.com/looker-studio.

Introduzione all'SDK Embed

L'SDK Embed di Looker è una libreria di funzioni che puoi aggiungere al codice dell'applicazione web basata su browser per gestire dashboard, Look ed esplorazioni incorporati nella tua app web. L'SDK Embed facilita l'incorporamento nei seguenti modi:

Forniscono l'incapsulamento dei contenuti incorporati senza dover creare manualmente elementi HTML.
Fornisce una comunicazione point-to-point in modo da non creare comunicazioni cross-frame. L'SDK Embed gestisce la trasmissione dei messaggi interdominio tra la pagina web dell'host e i contenuti Looker incorporati utilizzando un canale di messaggi dedicato.

Senza l'SDK Embed, puoi richiamare o rispondere agli eventi nei contenuti 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 Looker con eventi JavaScript devono creare gli elementi HTML per ospitare i contenuti incorporati e affidarsi agli eventi di trasmissione delle finestre per le comunicazioni tra l'app web e i contenuti incorporati.

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

L'SDK Embed di Looker si trova nel codice lato client dell'applicazione web e gestisce il contesto di incorporamento e i contenuti di Looker. (l'SDK Embed non fornisce accesso all'API Looker).
L'API Looker risiede sul server con la 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 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. Assicurati di scrivere il codice JavaScript in modo appropriato per tenere conto della gestione degli eventi di diversi browser.

Esempio rapido

Questo esempio crea un contesto di incorporamento di Looker, lo inserisce in un elemento DOM con ID dashboard e poi mostra una dashboard con ID 11 nel contesto di incorporamento di Looker. Gli eventi dashboard:run:start e dashboard:run:complete vengono utilizzati per aggiornare lo stato dell'interfaccia utente della finestra di incorporamento; inoltre, viene creato uno script con un pulsante con ID run per 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 Demo dell'SDK Embed.

Configurazione dell'SDK Embed di Looker

L'SDK Embed di Looker utilizza un pattern di interfaccia scorrevole. Dopo aver installato l'SDK Embed, dovrai creare i contenuti incorporati e collegarti ai contenuti incorporati.

Installazione dell'SDK Embed

Puoi ottenere la libreria SDK Embed di Looker tramite il gestore di pacchetti di nodi (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:

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

npm install
npm start

Costruire i contenuti incorporati

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

Includi il numero di 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 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 builder con una dashboard id o con un url che fa riferimento a una dashboard (creata dal processo descritto nella pagina della documentazione relativa all'incorporamento firmato).

LookerEmbedSDK.createDashboardWithId(id)

LookerEmbedSDK.createDashboardWithUrl(url)

Puoi quindi aggiungere altri attributi allo strumento per la creazione di contenuti per completare la configurazione. Ad esempio, puoi specificare il punto della pagina web in cui inserire l'interfaccia utente incorporata di Looker. La seguente chiamata inserisce l'interfaccia utente incorporata di Looker all'interno di un elemento HTML con un valore ID di 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 concludere, crea l'elemento incorporato:

.build()

Connessione ai contenuti incorporati

Se vuoi inviare e ricevere messaggi dall'elemento incorporato, devi chiamare connect(), che restituisce un valore Promise che si risolve nell'interfaccia di comunicazione dell'elemento specificato:

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

Creare URL per l'SDK

La documentazione principale per gli URL incorporati firmati da Looker è disponibile nella pagina della documentazione relativa all'incorporamento firmato. L'unica differenza durante la creazione degli 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 se l'SDK è presente e di sfruttare le funzionalità aggiuntive fornite dall'SDK. Ad esempio:

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

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

L'endpoint di autenticazione

Poiché il secret di incorporamento deve essere protetto con attenzione, non è possibile creare URL di incorporamento firmati nel browser. Per rendere la procedura più semplice e sicura, puoi seguire questi passaggi:

Implementa una funzione di firma dell'URL nel tuo server web. Il server deve restituire un URL firmato utilizzando uno dei processi documentati nel repository GitHub Looker Embed SSO Examples.
Trasmetti l'URL di incorporamento firmato all'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 utilizzando solo un ID, il relativo URL di incorporamento viene generato utilizzando il tipo di elemento, l'host Looker fornito ed eventuali parametri forniti. Ad esempio:

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

L'esempio precedente chiamerà l'endpoint /looker_auth e restituirà un URL di incorporamento firmato che può essere utilizzato per creare i contenuti incorporati:

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

Configurazione avanzata dell'autenticazione

L'endpoint di autenticazione può essere ulteriormente configurato per consentire intestazioni delle richieste personalizzate e il supporto CORS. Puoi farlo passando 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 nodo

In server_utils/auth_utils.ts è fornito un metodo helper per la firma createSignedUrl(). 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 });
});

Questa è 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 è ancora necessario con un segnaposto vuoto nell'URL di incorporamento.

Risoluzione dei problemi

Logging

L'SDK Embed è basato sulle chat. Chatty utilizza il debug per il logging. Puoi abilitare il logging nella 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 = ''