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:

Fornire l'incapsulamento dei contenuti incorporati senza la necessità di creare manualmente elementi HTML.
Fornire una comunicazione point-to-point in modo che non ci siano comunicazioni cross-frame. L'SDK Embed gestisce il trasferimento dei messaggi tra domini tra la pagina web host e i contenuti di 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 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 si trova nel codice lato client della tua applicazione web e gestisce il contesto e i contenuti incorporati 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 appropriato per 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 e 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 Embed SDK demo (Demo dell'SDK Embed).

Configurazione dell'SDK Embed di Looker

L'SDK Embed di Looker utilizza un pattern di interfaccia fluida. Dopo aver installato l'SDK Embed, devi costruire i contenuti incorporati e collegarti ai contenuti incorporati.

Installazione dell'SDK Embed

Puoi recuperare la libreria Embed SDK di Looker tramite il Node Package Manager (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 Embed di Looker utilizzando il repository dell'SDK Looker Embed:

Installa Node.js, se non l'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

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. 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 builder con una dashboard id o con un url che fa riferimento a una dashboard (creata dal processo descritto nella pagina della documentazione Incorporamento firmato).

LookerEmbedSDK.createDashboardWithId(id)

LookerEmbedSDK.createDashboardWithUrl(url)

Potrai quindi aggiungere altri attributi allo strumento per la creazione di contenuti 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')
)

Termina la creazione dell'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 firmato di Looker si trova nella pagina della documentazione 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 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.

Endpoint di autenticazione

Poiché il secret di incorporamento deve essere attentamente protetto, gli URL di incorporamento firmati non possono essere creati nel browser. Per rendere la procedura più semplice e sicura, puoi procedere nel seguente modo:

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 incorporato viene creato utilizzando solo un ID, il relativo URL di incorporamento viene generato utilizzando il tipo di elemento, l'host 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 di autenticazione avanzata

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 è stato 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 è comunque obbligatorio con un segnaposto vuoto nell'URL di incorporamento.

Risoluzione dei problemi

Logging

L'SDK Embed si basa sulla chat. Chatty utilizza il 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 = ''