Présentation du SDK d'ingestion

Le SDK d'intégration 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'ingestion facilite l'intégration de la manière suivante:

  • Fournit 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 cadres. Le SDK d'ingestion gère la transmission de messages interdomaines entre votre page Web hôte et votre contenu Looker intégré, à l'aide d'un canal de messages dédié.

Sans le SDK Embed, vous pouvez appeler ou répondre aux événements dans le contenu Looker intégré à 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 à l'aide d'événements JavaScript doivent créer les éléments HTML pour héberger le contenu intégré et s'appuyer sur des événements de diffusion de fenêtre pour les communications entre l'application Web et le contenu intégré.

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

  • Le SDK d'ingestion Looker se trouve dans le code côté client de votre application Web et gère le contexte et le contenu d'ingestion 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 se trouvent dans le code des applications autres que les navigateurs pour fournir un accès aux fonctions de l'API Looker.

Notez que Looker ne contrôle pas l'ordre dans lequel les navigateurs distribuent les événements aux applications Web. Cela signifie que l'ordre des événements n'est pas garanti entre les navigateurs et les plates-formes. Veillez à écrire votre code JavaScript de manière appropriée pour tenir compte de la gestion des événements dans les 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 permettent de mettre à jour l'état de l'UI de la fenêtre d'intégration. Un bouton avec un ID de run est programmé 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émo du SDK Embed.

Configurer le SDK d'ingestion Looker

Le SDK d'ingestion Looker utilise un modèle d'interface fluide. Une fois que vous avez installé le SDK Embed, vous pouvez créer le contenu intégré et vous y connecter. Une fois la connexion établie, l'application d'hébergement peut interagir avec le contenu intégré.

Installer le SDK d'ingestion

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

Pour installer le SDK d'ingestion Looker à l'aide du dépôt du SDK d'ingestion 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 intégrée Looker signée. Ces serveurs sont utilisés par l'ensemble du contenu intégré. 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éé à l'aide d'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 compilateur avec un id de tableau de bord ou un url qui fait référence à un tableau de bord (créé par le processus décrit sur la page de documentation sur l'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 où insérer l'UI d'intégration Looker sur votre page Web. L'appel suivant place l'UI d'intégration Looker dans un élément HTML avec une valeur d'ID de 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 de compilation:

.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 utilisé pour l'iFrame réelle. 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ée par le deuxième argument de l'appel initCookieless est appelé. Le point de terminaison ou la fonction doit renvoyer des jetons sans cookie, en particulier les jetons d'authentification et de navigation. Les jetons sont ajoutés à l'URL de connexion d'intégration.
  3. Privé: 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 décorée avec les 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 tant qu'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()
}

L'iFrame n'a pas besoin d'être recréée lorsqu'un autre contenu doit être chargé. À la place, 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 intégré 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')

Si vous devez créer une nouvelle iFrame, le SDK Embed n'appellera plus la signature ni n'acquérra plus les points de terminaison de session. Il crée plutôt l'iframe src directement à partir du compilateur. Si vous devez créer une nouvelle session d'intégration, vous devez réinitialiser le SDK d'intégration comme suit:

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

Point de terminaison d'authentification par URL signée

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

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 propre à l'utilisateur à l'origine de la requête. Le processus backend peut générer lui-même l'URL d'ingestion signée à l'aide d'un secret d'ingestion, ou générer l'URL en appelant l'API Looker Create Signed Embed URL. La génération et la signature manuelles d'une 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.

Vous trouverez un exemple JavaScript d'une méthode d'assistance qui génère une URL signée, createSignedUrl(), 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 à l'intégration sans cookie. Pour en savoir plus, consultez Intégration sans cookie.

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 d'ingestion est basé sur chatty. Chatty utilise le débogage pour la journalisation. Vous pouvez activer la journalisation dans une console de navigateur à l'aide de la commande suivante:

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