Présentation du SDK d'ingestion

Remarque : Cette page est une référence pour le SDK d'intégration 2.0.0. Bien que l'API 2.0.0 soit rétrocompatible avec le SDK d'intégration 1.8.x, l'implémentation sous-jacente a changé pour certaines fonctionnalités. Le SDK 1.8.x a exporté un certain nombre de classes. Le SDK 2.0.0 remplace ces classes par des interfaces marquées comme obsolètes (des interfaces alternatives sont identifiées). Nous recommandons aux applications d'utiliser les interfaces qui ont un préfixe "I" (les interfaces qui ont des préfixes sont identiques à celles qui n'en ont pas). Les applications mises à niveau vers le SDK 2.0.0 devraient continuer à fonctionner et à se comporter comme auparavant. Pour profiter des améliorations de l'API, une refactorisation sera nécessaire. Les modifications majeures suivantes sont incluses dans le SDK d'intégration 2.0.0 :

• La navigation entre les tableaux de bord, les explorations et les présentations ne nécessite plus la recréation d'un iframe. Au lieu de cela, les méthodes loadDashboard, loadLook, loadExplore et loadUrl peuvent être utilisées pour naviguer dans l'iframe Looker.
• connect renvoie désormais une connexion unifiée plutôt qu'une connexion liée uniquement à un tableau de bord, une présentation ou une exploration. La connexion unifiée permet aux applications d'intégration de détecter un utilisateur naviguant dans l'iframe.
• La prise en charge de contenu intégré Looker supplémentaire a été ajoutée pour les rapports Looker et les visualisations de requêtes.

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 présentations, les rapports et les explorations intégrés dans votre application Web.

Remarque : Les rapports Looker sont disponibles lorsque la fonctionnalité de rapports Looker est activée. Les rapports peuvent être intégrés à l'aide de la méthode d'intégration signée, de la méthode d'intégration sans cookies ou de la méthode d'intégration privée. Pour en savoir plus, consultez Intégrer des rapports Looker.

Le SDK d'intégration facilite l'intégration des manières suivantes :

• Fournir l'encapsulation du contenu intégré sans avoir à créer manuellement des éléments HTML.
• Fournir une communication point à point afin qu'il n'y ait pas de communication inter-frame. Le SDK d'intégration 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 d'intégration, 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 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'intégration Looker réside dans le code côté client de votre application Web et gère le contexte et le contenu d'intégration Looker. (Le SDK d'intégration ne fournit pas d'accès à 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.

Sachez 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 sur tous les navigateurs ni toutes les 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 bouton avec l'ID run est scripté 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 démonstration du SDK d'intégration.

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 d'intégration, vous créez le contenu intégré et vous vous connectez à celui-ci. 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 d'intégration Looker.

Pour installer le SDK d'intégration Looker à l'aide du dépôt du 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 intégrée Looker signée. Ces serveurs sont utilisés par tout le contenu intégré. Pour l'intégration privée, omettez le point de terminaison de signature.

Remarque : Incluez le numéro de port s'il est nécessaire pour accéder au serveur Looker à partir des clients de navigateur. Par exemple : looker.example.com:443

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

Le contenu intégré est ensuite créé en plusieurs é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 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 des attributs supplémentaires au compilateur pour terminer la configuration.

Remarque : Les fonctions create[ContentType]WithUrl peuvent être utilisées avec l’intégration signée et sans cookies à partir du SDK d’intégration 2.0.0. Avant le SDK d'intégration 2.0.0, l'intégration sans cookies ne prenait en charge que create[ContentType]WithId.

Par exemple, vous pouvez spécifier où insérer l'UI d'intégration Looker dans votre page Web. L'appel suivant place l'UI d'intégration Looker dans un élément HTML avec une valeur d'ID 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éel. 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 cookies : le point de terminaison ou la fonction spécifié par le deuxième argument de l'appel initCookieless est appelé. Le point de terminaison ou la fonction doit renvoyer des jetons sans cookies, en particulier les jetons d'authentification et de navigation. Les jetons sont ajoutés à l'URL de connexion intégrée.
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 compilateur 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 une 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 d'intégration 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éé lorsque différents contenus doivent être chargés. Au lieu de cela, les méthodes de connexion loadDashboard, loadLook, loadExplore ou loadUrl peuvent être utilisées. Les méthodes loadDashboard, loadLook et loadExplore acceptent un id. La méthode loadUrl accepte une URL d'intégration, et cette méthode 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 d'intégration n'appellera plus les points de terminaison de signature ni d'acquisition de session. Au lieu de cela, il construira directement l'iframe src à partir du compilateur. S'il est nécessaire de créer une session d'intégration, le SDK d'intégration devra être réinitialisé de la manière suivante :

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

Point de terminaison d'authentification d'URL signée

Cette section ne s'applique pas à l'intégration sans cookies. 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 demandeur. Le processus 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 d'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 d'une 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 d'URL signée

Cette section ne s'applique pas à l'intégration sans cookies. 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 prise en charge de 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'intégration est basé sur chatty. Chatty utilise le débogage pour la journalisation. Vous pouvez activer la journalisation dans une console de navigateur avec 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 = ''