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

Questa pagina è stata tradotta dall'API Cloud Translation.

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 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 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 codice JavaScript in modo da tenere conto della gestione degli eventi dei diversi browser.

Esempio rapido

Questo esempio costruisce 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, mentre un pulsante con ID run viene associato a uno script per l'invio di 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 Embed SDK demo (Demo dell'SDK Embed).

Configurazione dell'SDK di incorporamento di Looker

L'SDK Embed di Looker utilizza un pattern di interfaccia fluido. Dopo aver installato l'SDK Embed, crea i contenuti incorporati e connettiti ai 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 relativo repository:

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

Creazione dei contenuti incorporati

Innanzitutto, inizializza l'SDK con l'indirizzo del tuo server web e, facoltativamente, l'endpoint sul server che eseguirà l'autenticazione. Questi 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')

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 con la procedura descritta nella pagina della documentazione relativa all'embedding firmato).

LookerEmbedSDK.createDashboardWithId(id)

LookerEmbedSDK.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')

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 messaggi all'elemento incorporato e ricevere messaggi da questo, devi chiamare connect(), che restituisce una promessa che risolve nell'interfaccia di comunicazione dell'elemento specificato:

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

Creazione di URL per l'SDK

La documentazione principale per gli URL di incorporamento firmati di Looker è disponibile nella pagina della documentazione relativa all'incorporamento firmato. L'unica differenza nella creazione degli URL per l'SDK è che dovrai 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 la presenza dell'SDK 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 auth

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

Implementa una funzione di firma dell'URL nel tuo server web. Il server deve restituire un URL firmato utilizzando una delle procedure descritte nel repository GitHub Esempi di SSO di Looker Embed.
Passa l'URL di incorporamento firmato all'endpoint di firma nell'SDK di incorporamento. 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 di Looker fornito e gli 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 configurato ulteriormente per consentire intestazioni delle richieste personalizzate e il supporto CORS. Puoi farlo passando 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 per i nodi

In server_utils/auth_utils.ts è fornito un metodo di assistenza alla 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 è comunque obbligatorio con un segnaposto vuoto nell'URL di incorporamento.

Risoluzione dei problemi

Logging

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 = ''