Présentation du SDK d'ingestion

Le SDK Embed de Looker est une bibliothèque de fonctions que vous pouvez ajouter au code de votre application Web basée sur un navigateur pour gérer les tableaux de bord, les Looks, les rapports et les explorations intégrés dans votre application Web.

Le SDK d'intégration facilite l'intégration de différentes manières :

  • Fournir l'encapsulation du contenu intégré sans avoir à créer manuellement des éléments HTML.
  • Fournit une communication point à point afin qu'il n'y ait pas de communication entre les frames. Le SDK d'intégration gère le transfert de messages entre domaines entre votre page Web hôte et votre contenu Looker intégré, en utilisant un canal de messages dédié.

Sans le SDK Embed, vous pouvez appeler des événements dans le contenu Looker intégré ou y répondre à l'aide d'événements JavaScript tels que dashboard:run:start ou page:changed, qui sont décrits sur la page de documentation Événements JavaScript intégrés. Les développeurs qui intègrent du contenu Looker avec des événements JavaScript doivent créer les éléments HTML pour héberger le contenu intégré et s'appuyer sur les événements de diffusion de fenêtre pour la communication entre l'application Web et le contenu intégré.

Notez que le SDK Looker Embed est différent de l'API Looker et du SDK de l'API Looker :

  • Le SDK d'intégration Looker se trouve dans le code côté client de votre application Web et gère le contexte et le contenu d'intégration Looker. (Le SDK Embed ne permet pas d'accéder à l'API Looker.)
  • L'API Looker réside sur le serveur avec votre instance Looker et exécute des commandes sur le serveur Looker.
  • Les SDK clients de l'API Looker résident dans le code des applications non basées sur un navigateur pour fournir un accès aux fonctions de l'API Looker.

Notez que Looker ne contrôle pas l'ordre dans lequel les navigateurs envoient des événements aux applications Web. Cela signifie que l'ordre des événements n'est pas garanti sur les différents navigateurs ou plates-formes. Veillez à écrire votre code JavaScript de manière appropriée pour tenir compte de la gestion des événements des différents navigateurs.

Exemple rapide

Dans cet exemple, un tableau de bord avec l'ID 11 est créé dans un élément DOM avec l'ID embed_container. Les événements dashboard:run:start et dashboard:run:complete sont utilisés pour mettre à jour l'état de l'UI de la fenêtre d'intégration, et un script est associé à un bouton dont l'ID est run pour envoyer un message dashboard:run au tableau de bord.

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

Un exemple plus complet est décrit sur la page de documentation de la démonstration du SDK Embed.

Configurer le SDK d'intégration Looker

Le SDK d'intégration Looker utilise un modèle d'interface fluide. Une fois que vous avez installé le SDK Embed, vous devez créer le contenu intégré et vous connecter au contenu intégré. L'application hôte peut interagir avec le contenu intégré une fois la connexion établie.

Installer le SDK d'intégration

Vous pouvez obtenir la bibliothèque du SDK d'intégration de Looker via le gestionnaire de packages Node (NPM) à l'adresse https://www.npmjs.com/package/@looker/embed-sdk. Toutefois, si vous souhaitez consulter l'exemple de code ou la démonstration, vous devez plutôt utiliser le dépôt du SDK Looker Embed.

Pour installer le SDK d'intégration Looker à l'aide du dépôt SDK d'intégration Looker, procédez comme suit :

  1. Installez Node.js si ce n'est pas déjà fait.
  2. Téléchargez ou clonez le dépôt /looker-open-source/embed-sdk.
  3. Dans une fenêtre de terminal, accédez au répertoire /embed-sdk et exécutez les commandes suivantes :
npm install
npm start

Créer le contenu intégré

Commencez par initialiser le SDK avec l'adresse du serveur Looker et le point de terminaison du serveur d'application d'intégration qui créera une URL de connexion Looker intégrée signée. Ces serveurs sont utilisés par tous les contenus intégrés. Pour l'intégration privée, omettez le point de terminaison de signature.

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

Le contenu intégré est ensuite créé en suivant une série d'étapes pour définir ses paramètres. Certains de ces paramètres sont facultatifs, d'autres sont obligatoires.

Le processus commence par la création du générateur avec un tableau de bord id ou avec un url qui fait référence à un tableau de bord (créé par le processus décrit sur la page de documentation Intégration signée).

getEmbedSDK().createDashboardWithId('id')

ou

getEmbedSDK().createDashboardWithUrl('url')

Vous pouvez ensuite ajouter d'autres attributs au générateur pour terminer la configuration.

Par exemple, vous pouvez spécifier l'emplacement de l'UI Looker à insérer dans votre page Web. L'appel suivant place l'UI d'intégration Looker dans un élément HTML dont la valeur d'ID est dashboard :

.appendTo('#dashboard')

Ajoutez des gestionnaires d'événements :

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

Créez un client intégré en appelant la méthode build :

.build()

Se connecter au contenu intégré

Une fois le client créé, appelez connect pour créer l'iframe. Le processus de connexion crée l'attribut src qui est utilisé pour l'iFrame. La façon dont la valeur src est générée dépend de la façon dont le SDK d'intégration est initialisé :

  1. Signé : le point de terminaison spécifié par le deuxième argument de l'appel init est appelé. Le point de terminaison doit renvoyer une URL de connexion intégrée signée.
  2. Sans cookie : le point de terminaison ou la fonction spécifiés par le deuxième argument de l'appel initCookieless sont appelés. Le point de terminaison ou la fonction sont censés renvoyer des jetons sans cookie, en particulier les jetons d'authentification et de navigation. Les jetons sont ajoutés à l'URL de connexion intégrée.
  3. Privée : la connexion d'intégration est privée si le deuxième argument de l'appel init n'est pas fourni. Dans ce cas, l'URL est dérivée du générateur et enrichie des paramètres requis pour l'intégration Looker. Pour l'intégration privée, l'utilisateur doit déjà être connecté à Looker ou l'URL d'intégration doit inclure le paramètre allow_login_screen=true.

connect renvoie un Promise qui se résout en interface de connexion pour l'iFrame intégré.

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

Interagir

Le SDK Embed 2.0.0 renvoie une connexion unifiée qui permet d'interagir avec tous les types de contenu Looker. L'application d'intégration peut déterminer le type de contenu affiché et interagir en conséquence.

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

Il n'est pas nécessaire de recréer l'iFrame lorsque différents contenus doivent être chargés. Vous pouvez utiliser les méthodes de connexion loadDashboard, loadLook, loadExplore ou loadUrl. Les méthodes loadDashboard, loadLook et loadExplore acceptent un id. La méthode loadUrl accepte un URL d'intégration et peut être utilisée pour spécifier des paramètres supplémentaires (tels que des filtres).

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

S'il est nécessaire de créer un iframe, le SDK Embed n'appellera plus les points de terminaison de signature ou d'acquisition de session. Au lieu de cela, il construira l'iframe src directement à partir du générateur. Si vous devez créer une session d'intégration, vous devrez réinitialiser le SDK Embed de la manière suivante :

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

Point de terminaison d'authentification par URL signée

Cette section ne s'applique pas aux intégrations sans cookie. Pour en savoir plus, consultez Intégration sans cookies.

Pour utiliser le SDK d'intégration, vous devez fournir un service de backend qui gère la signature de l'URL d'intégration. Ce service est appelé par le SDK d'intégration pour générer une URL signée unique pour l'utilisateur qui en fait la demande. Le processus de backend peut générer lui-même l'URL d'intégration signée à l'aide d'un secret d'intégration, ou il peut générer l'URL en appelant l'API Looker Create Signed Embed URL. La génération et la signature manuelles des URL évitent d'appeler l'API Looker, ce qui réduit la latence. L'appel de l'API Looker nécessite moins de code et est plus facile à gérer.

Un exemple JavaScript de méthode d'assistance qui génère une URL signée, createSignedUrl(), est disponible dans server/utils/auth_utils.ts. Il est utilisé de la manière suivante :

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

Consultez l'exemple Python dans le dépôt.

Configuration avancée de l'authentification par URL signée

Cette section ne s'applique pas aux intégrations sans cookie. Pour en savoir plus, consultez Intégration sans cookies.

Vous pouvez configurer le point de terminaison d'authentification pour autoriser les en-têtes de requête personnalisés et la compatibilité CORS en transmettant un objet d'options à la méthode 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
})

Dépannage

Le SDK Embed est basé sur chatty. Chatty utilise debug pour la journalisation. Vous pouvez activer la journalisation dans une console de navigateur à l'aide de cette commande :

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