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 è possibile 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:

Incapsulare i contenuti incorporati senza dover creare manualmente gli elementi HTML.
Fornire comunicazioni point-to-point che non prevedono comunicazioni cross-frame. L'SDK Embed gestisce la trasmissione tra domini diversi dei messaggi tra 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 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 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. Assicurati di scrivere il tuo codice 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 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 un ID run è codificato 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 relativa all'incorporamento di SDK demo.

Configurare l'SDK Embed di Looker

L'SDK Embed di Looker utilizza un pattern di interfaccia fluente. Dopo aver installato l'SDK Embed, devi creare i contenuti incorporati e connetterti ai contenuti incorporati.

Installazione dell'SDK Embed

Puoi ottenere la libreria SDK Embed di Looker tramite il gestore di pacchetti del nodo (NPM) all'indirizzo https://www.npmjs.com/package/@looker/embed-sdk. Tuttavia, per vedere 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 di /looker-open-source/embed-sdk.
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 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 è necessaria per raggiungere il server Looker dai client del browser. Ad esempio: looker.example.com:443

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

In seguito, i contenuti incorporati vengono creati 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 dello strumento per la creazione con una dashboard id oppure una url che fa riferimento a una dashboard (creata dalla procedura descritta nella pagina della documentazione relativa all'incorporamento con Single Sign-On (SSO)).

LookerEmbedSDK.createDashboardWithId(id)

LookerEmbedSDK.createDashboardWithUrl(url)

Puoi quindi aggiungere ulteriori attributi al builder per completare la configurazione. Ad esempio, puoi specificare in che punto della tua pagina web puoi inserire la UI di incorporamento di Looker. La seguente chiamata posiziona l'UI di incorporamento di Looker all'interno di un elemento HTML con un valore ID pari a 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()

Connessione ai contenuti incorporati

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

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

Creare URL per l'SDK

La documentazione principale per gli URL di incorporamento SSO Looker è disponibile nella pagina della documentazione relativa all'incorporamento con 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 oltre ad altri parametri come i filtri e il parametro embed_domain. Questo parametro consente a Looker di determinare che l'SDK è presente e di usufruire delle funzionalità aggiuntive fornite dall'SDK. Ecco alcuni esempi:

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

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

L'endpoint di autenticazione

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

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 di Esempi Looker Embed SSO.
Passa l'URL SSO da incorporare 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. Ecco alcuni esempi:

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

Questa funzione chiamerà l'endpoint /looker_auth e restituirà un URL SSO 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 di autenticazione avanzata

L'endpoint di autenticazione può essere configurato ulteriormente per consentire le intestazioni delle richieste personalizzate e il supporto di CORS. A tal fine, trasmetti un oggetto options 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 nodi

In server_utils/auth_utils.ts è disponibile un metodo di supporto alla firma: createSignedUrl(). Il loro 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 è basato su chatty. Chatty utilizza il debug per il logging. 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 = ''