Introdução ao SDK Embed

O SDK de incorporação do Looker é uma biblioteca de funções que pode adicionar ao código da sua aplicação Web baseada no navegador para gerir painéis de controlo, Looks, relatórios e Explores incorporados na sua app Web.

O SDK Embed facilita a incorporação das seguintes formas:

  • Fornecer a encapsulagem do conteúdo incorporado sem a necessidade de criar manualmente elementos HTML.
  • Fornecer comunicação ponto a ponto para que não haja comunicação entre frames. O SDK de incorporação processa a transmissão de mensagens entre domínios entre a sua página Web de anfitrião e o seu conteúdo do Looker incorporado, usando um canal de mensagens dedicado.

Sem o SDK Embed, pode invocar ou responder a eventos no conteúdo do Looker incorporado através de eventos JavaScript, como dashboard:run:start ou page:changed, que são descritos na página de documentação Eventos JavaScript incorporados. Os programadores que incorporam conteúdo do Looker com eventos JavaScript têm de criar os elementos HTML para alojar o conteúdo incorporado e basear-se em eventos de transmissão de janelas para comunicações entre a app Web e o conteúdo incorporado.

Tenha em atenção que o SDK Looker Embed é diferente da API Looker e do SDK da API Looker:

  • O Looker Embed SDK reside no código do lado do cliente da sua aplicação Web e gere o contexto e o conteúdo de incorporação do Looker. (O SDK de incorporação não fornece acesso à API Looker.)
  • A API Looker reside no servidor com a sua instância do Looker e executa comandos no servidor do Looker.
  • Os SDKs do cliente da API Looker residem no código de aplicações que não são de navegador para fornecer acesso às funções da API Looker.

Tenha em atenção que o Looker não controla a ordem em que os navegadores enviam eventos para aplicações Web. Isto significa que a ordem dos eventos não é garantida em todos os navegadores ou plataformas. Certifique-se de que escreve o JavaScript adequadamente para ter em conta o processamento de eventos de diferentes navegadores.

Exemplo rápido

Neste exemplo, é criado um painel de controlo com um ID de 11 num elemento DOM com o ID embed_container. Os eventos dashboard:run:start e dashboard:run:complete são usados para atualizar o estado da IU da janela de incorporação, e um botão com um ID de run é programado para enviar uma mensagem dashboard:run para o painel de controlo.

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)
}

É descrito um exemplo mais completo na página de documentação da demonstração do SDK incorporado.

Configurar o SDK Looker Embed

O SDK Looker Embed usa um padrão de interface fluente. Depois de instalar o SDK Embed, cria o conteúdo incorporado e liga-se ao conteúdo incorporado. A aplicação de alojamento pode interagir com o conteúdo incorporado assim que a ligação for estabelecida.

Instalar o SDK Embed

Pode obter a biblioteca do SDK de incorporação do Looker através do gestor de pacotes de nós (NPM) em https://www.npmjs.com/package/@looker/embed-sdk. No entanto, se quiser ver o código de exemplo ou a demonstração, deve usar o repositório do SDK Looker Embed.

Para instalar o SDK Looker Embed através do repositório do SDK Looker Embed, siga estes passos:

  1. Instale o Node.js, se ainda não o tiver.
  2. Transfira ou clone o repositório /looker-open-source/embed-sdk.
  3. Numa janela do terminal, navegue para o diretório /embed-sdk e execute estes comandos:
npm install
npm start

Construir o conteúdo incorporado

Primeiro, inicialize o SDK com o endereço do servidor do Looker e o ponto final do servidor da aplicação de incorporação que vai criar um URL de início de sessão incorporado do Looker assinado. Estes servidores são usados por todo o conteúdo incorporado. Para a incorporação privada, omita o ponto final de assinatura.

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

Em seguida, o conteúdo incorporado é criado através de uma série de passos para definir os respetivos parâmetros. Alguns destes parâmetros são opcionais e outros são obrigatórios.

O processo começa com a criação do criador através de um painel de controlo id ou de um url que faz referência a um painel de controlo (criado pelo processo descrito na página de documentação Incorporação assinada).

getEmbedSDK().createDashboardWithId('id')

ou

getEmbedSDK().createDashboardWithUrl('url')

Em seguida, pode adicionar atributos adicionais ao criador para concluir a configuração.

Por exemplo, pode especificar em que parte da sua página Web quer inserir a IU de incorporação do Looker. A seguinte chamada coloca a IU de incorporação do Looker num elemento HTML com um valor de ID de dashboard:

.appendTo('#dashboard')

Adicione controladores de eventos:

.on('dashboard:run:start',
  () => updateStatus('Running')
)
.on('dashboard:run:complete',
  () => updateStatus('Done')
)

Crie um cliente incorporado chamando o método de criação:

.build()

A ligar ao conteúdo incorporado

Assim que o cliente for criado, chame connect para criar o iFrame. O processo de ligação cria o atributo src que é usado para o iFrame real. A forma como o valor src é gerado baseia-se na forma como o SDK de incorporação é inicializado:

  1. Assinada: o ponto final especificado pelo segundo argumento da chamada init é chamado. O ponto final deve devolver um URL de início de sessão incorporado assinado.
  2. Sem cookies: o ponto final ou a função especificada pelo segundo argumento da chamada initCookieless é chamado. Espera-se que o ponto final ou a função devolva tokens sem cookies, especificamente os tokens de autenticação e navegação. Os tokens são anexados ao URL de início de sessão de incorporação.
  3. Privado: a ligação de incorporação é privada se o segundo argumento da chamada init não for fornecido. Neste caso, o URL é derivado do criador e decorado com os parâmetros necessários para a incorporação do Looker. Para a incorporação privada, espera-se que o utilizador já tenha sessão iniciada no Looker ou que o URL de incorporação inclua o parâmetro allow_login_screen=true.

connect devolve um Promise que é resolvido para a interface de ligação do iFrame incorporado.

  .connect()
  .then((connection) => {
    // Save the connection
  })
  .catch(console.error)

Interagir

O SDK de incorporação 2.0.0 devolve uma ligação unificada que suporta a interação com todos os tipos de conteúdo do Looker. A aplicação de incorporação pode determinar o tipo de conteúdo que está a ser apresentado e interagir em conformidade.

if (connection.getPageType() === 'dashboards') {
  connection.asDashboardConnection().run()
} else (connection.getPageType() === 'looks') {
  connection.asLookConnection().run()
} else (connection.getPageType() === 'explore') {
  connection.asExploreConnection().run()
}

Não é necessário recriar o iFrame quando é preciso carregar conteúdo diferente. Em alternativa, podem ser usados os métodos de associação loadDashboard, loadLook, loadExplore ou loadUrl. Os métodos loadDashboard, loadLook e loadExplore aceitam um id. O método loadUrl aceita uma incorporação URL, e este método pode ser usado para especificar parâmetros adicionais (como filtros).

connection.loadDashboard('42')
// OR
connection.loadUrl('/embed/dashboards/42?state=california')

Se for necessário criar um novo iFrame, o SDK de incorporação não chama novamente os pontos finais de assinatura nem de aquisição de sessão. Em vez disso, vai construir o iframe src diretamente a partir do criador. Se for necessário criar uma nova sessão de incorporação, o SDK de incorporação tem de ser reinicializado da seguinte forma:

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

Ponto final de autenticação de URL assinado

Esta secção não se aplica à incorporação sem cookies. Consulte o artigo Incorporação sem cookies para ver detalhes.

Para usar o SDK de incorporação, tem de fornecer um serviço de back-end que processe a assinatura do URL de incorporação. Este serviço é chamado pelo SDK Embed para gerar um URL assinado exclusivo do utilizador que está a fazer o pedido. O processo de back-end pode gerar o próprio URL incorporado assinado através de um segredo de incorporação ou pode gerar o URL chamando a API Looker Create Signed Embed URL. A geração e a assinatura manuais de URLs evitam chamar a API Looker, o que diminui a latência. Chamar a API Looker requer menos código e é mais fácil de manter.

Pode encontrar um exemplo de JavaScript de um método auxiliar que gera um URL assinado, createSignedUrl(), em server/utils/auth_utils.ts. É usado da seguinte forma:

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 })
})

Consulte o exemplo de Python no repositório.

Configuração de autenticação avançada de URL assinado

Esta secção não se aplica à incorporação sem cookies. Consulte o artigo Incorporação sem cookies para ver detalhes.

Pode configurar o ponto final de autenticação para permitir cabeçalhos de pedidos personalizados e compatibilidade com CORS transmitindo um objeto de opções ao método 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
})

Resolução de problemas

O SDK Embed é criado com base no chatty. O Chatty usa a opção debug para o registo. Pode ativar o registo numa consola do navegador com este 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 = ''