Você está visualizando a documentação do Looker. Para acessar a documentação do Looker Studio, acesse https://support.google.com/looker-studio.

Esta página foi traduzida pela API Cloud Translation.

Introdução ao SDK de incorporação

O SDK de incorporação do Looker é uma biblioteca de funções que você pode adicionar ao código do seu aplicativo da Web baseado em navegador para gerenciar painéis, Looks e Análises detalhadas incorporados no seu app da Web. O SDK de incorporação facilita a incorporação das seguintes maneiras:

Fornece o encapsulamento do conteúdo incorporado sem a necessidade de criar elementos HTML manualmente.
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 página da Web do host e o conteúdo incorporado do Looker, usando um canal de mensagens dedicado.

Sem o SDK de incorporação, é possível invocar ou responder a eventos no conteúdo incorporado do Looker usando eventos JavaScript, como dashboard:run:start ou page:changed, que são descritos na página de documentação Eventos JavaScript incorporados. Os desenvolvedores que incorporam conteúdo do Looker com eventos JavaScript precisam criar os elementos HTML para armazenar o conteúdo incorporado e depender de eventos de transmissão de janela para comunicações entre o app da Web e o conteúdo incorporado.

O SDK de incorporação do Looker é diferente da API e do SDK do Looker:

O SDK de incorporação do Looker fica no código do lado do cliente do seu aplicativo da Web e gerencia o contexto e o conteúdo de incorporação do Looker. O SDK de incorporação não oferece acesso à API Looker.
A API do Looker fica no servidor com sua instância do Looker e executa comandos no servidor do Looker.
Os SDKs de cliente da API Looker residem no código de aplicativos que não são do navegador para facilitar o acesso às funções da API Looker.

O Looker não controla a ordem em que os navegadores enviam eventos para aplicativos da Web. Isso significa que a ordem dos eventos não é garantida em todos os navegadores ou plataformas. Escreva seu JavaScript de maneira adequada para considerar o processamento de eventos de diferentes navegadores.

Exemplo rápido

Este exemplo constrói um contexto de incorporação do Looker, o insere em um elemento DOM com um ID de dashboard e exibe um painel com um ID de 11 no contexto de incorporação do Looker. Os eventos dashboard:run:start e dashboard:run:complete são usados para atualizar o estado da interface da janela de incorporação, e um botão com um ID de run é programado para enviar uma mensagem dashboard:run ao painel.

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

Um exemplo mais completo é descrito na página de documentação da demonstração do SDK de incorporação.

Configurar o SDK de incorporação do Looker

O SDK de incorporação do Looker usa um padrão de interface fluída. Depois de instalar o SDK de incorporação, construa o conteúdo incorporado e se conecte a ele.

Como instalar o SDK de incorporação

Você pode acessar a biblioteca do SDK de incorporação do Looker pelo gerenciador de pacotes do nó (NPM) em https://www.npmjs.com/package/@looker/embed-sdk. No entanto, se você quiser conferir o código de exemplo ou a demonstração, use o repositório do SDK do Looker Embed.

Para instalar o SDK de incorporação do Looker usando o repositório do SDK de incorporação do Looker:

Instale o Node.js, se ainda não tiver.
Faça o download ou clone o repositório /looker-open-source/embed-sdk.
Em uma janela de terminal, navegue até o diretório /embed-sdk e execute estes comandos:

npm install
npm start

Como criar o conteúdo incorporado

Primeiro, inicialize o SDK com o endereço do seu servidor da Web e, opcionalmente, o endpoint no servidor que vai realizar a autenticação. Eles são usados por todo o conteúdo incorporado.

Inclua o número da porta se ele for necessário para acessar o servidor do Looker de clientes do navegador. Por exemplo: looker.example.com:443

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

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

O processo começa com a criação do builder com um id de painel ou com um url que se refere a um painel (criado pelo processo descrito na página de documentação Inserção assinada).

LookerEmbedSDK.createDashboardWithId(id)

LookerEmbedSDK.createDashboardWithUrl(url)

Em seguida, adicione outros atributos ao criador para concluir a configuração. Por exemplo, é possível especificar onde inserir a UI de incorporação do Looker na sua página da Web. A chamada a seguir coloca a UI incorporada do Looker em um elemento HTML com um valor de ID de dashboard:

.appendTo('#dashboard')

É possível adicionar manipuladores de eventos:

.on('dashboard:run:start',
  () => updateState('#dashboard-state', 'Running')
)
.on('dashboard:run:complete',
  () => updateState('#dashboard-state', 'Done')
)

Você termina criando o elemento incorporado:

.build()

Como se conectar ao conteúdo incorporado

Se você quiser enviar e receber mensagens do elemento incorporado, chame connect(), que retorna uma promessa que é resolvida na interface de comunicação do elemento:

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

Como criar URLs para o SDK

A documentação principal para URLs de incorporação assinados do Looker está na página de documentação Incorporação assinada. A única diferença ao criar URLs para o SDK é que você precisa adicionar um parâmetro sdk=2 ao URL de incorporação com outros parâmetros, como filtros e o parâmetro embed_domain. Esse parâmetro permite que o Looker determine se o SDK está presente e aproveite outros recursos fornecidos por ele. Exemplo:

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

O SDK não pode adicionar esse parâmetro porque ele faz parte do URL de incorporação assinado.

Endpoint de autenticação

Como o segredo de incorporação precisa ser protegido com cuidado, não é possível criar URLs de incorporação assinados no navegador. Para facilitar e aumentar a segurança do processo, siga estas etapas:

Implemente uma função de assinatura de URL no servidor da Web. O servidor precisa retornar um URL assinado usando um dos processos documentados no repositório do GitHub Looker Embed SSO Examples.
Transmita o URL de incorporação assinado para esse endpoint de assinatura no SDK de incorporação. O local do endpoint é especificado pelo parâmetro authUrl em LookerEmbedSDK.init().

Se especificado, sempre que um elemento de incorporação for criado usando apenas um ID, o URL de incorporação será gerado usando o tipo do elemento, o host do Looker fornecido e todos os parâmetros fornecidos. Exemplo:

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

O exemplo anterior vai chamar o endpoint /looker_auth e retornar um URL de incorporação assinado que pode ser usado para criar o conteúdo incorporado:

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

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

O endpoint de autenticação pode ser configurado para permitir cabeçalhos de solicitação personalizados e suporte a CORS. Para fazer isso, transmita um objeto de opções para o método 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
  })

Node helper

Um método auxiliar de assinatura createSignedUrl() é fornecido em server_utils/auth_utils.ts. O uso é o seguinte:

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

Esta é a estrutura de dados do usuário:

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: {}
}

O parâmetro access_filters foi removido no Looker 3.10, mas ainda é necessário com um marcador de posição vazio no URL de incorporação.

Solução de problemas

Geração de registros

O SDK incorporado é criado com base no chatty. O Chatty usa debug para gerar registros. É possível ativar a geração de registros em um console 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 = ''