Présentation du SDK Embed

Le SDK Embed de Looker est une bibliothèque de fonctions que vous pouvez ajouter au code de votre application Web intégrée au navigateur pour gérer des tableaux de bord, des styles et des explorations intégrés dans votre application Web. Le SDK Embed facilite l'intégration des manières suivantes:

  • Fournir les encapsulations du contenu intégré sans qu'il soit nécessaire de créer manuellement des éléments HTML
  • Communication point à point pour éviter toute communication interframe. Le SDK Embed gère le message interdomaine qui transite entre votre page Web hôte et votre contenu Looker intégré, en utilisant un canal de message 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 à des é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 Embed Looker est différent de l'API Looker et du SDK API Looker:

  • Le SDK d'intégration de Looker se trouve dans le code côté client de votre application Web et gère le contexte et le contenu d'intégration de Looker. (Le SDK Embed ne fournit pas d'accès à l'API Looker.)
  • L'API Looker réside sur le serveur avec votre instance Looker et exécute les commandes sur le serveur Looker.
  • Les SDK clients de l'API Looker se trouvent dans le code des applications autres que les navigateurs afin de faciliter l'accès aux fonctions de l'API Looker.

Sachez que Looker ne contrôle pas l'ordre dans lequel les navigateurs envoient les événements aux applications Web. Cela signifie que l'ordre des événements n'est pas garanti sur tous les navigateurs ou plates-formes. Veillez à rédiger votre code JavaScript de façon à tenir compte de la gestion des événements dans les différents navigateurs.

Exemple rapide

Cet exemple construit un contexte d'intégration Looker, l'insère dans un élément DOM avec l'ID dashboard, puis affiche un tableau de bord avec l'ID 11 dans le contexte d'intégration Looker. Les événements dashboard:run:start et dashboard:run:complete permettent de mettre à jour l'état de l'interface utilisateur de la fenêtre d'intégration. Un bouton portant l'ID run est envoyé pour envoyer un message dashboard:run au tableau de bord.

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

Vous trouverez un exemple plus complet sur la page de démonstration du SDK Embed.

Configurer le SDK Embed Looker

Le SDK Embed Looker utilise un modèle d'interface courant. Une fois que vous avez installé le SDK Embed, créez le contenu intégré et connectez-vous au contenu intégré.

Installer le SDK Embed

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

Pour installer le SDK Embed Looker à l'aide du dépôt du SDK Embed Looker:

  1. Si ce n'est pas déjà fait, installez Node.js.
  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

Construire le contenu intégré

Tout d'abord, initialisez le SDK avec l'adresse de votre serveur Web et, éventuellement, le point de terminaison de votre serveur qui effectuera l'authentification. Ils sont utilisés par tous les contenus intégrés.

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

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

Le contenu intégré est ensuite créé à l'aide d'une série d'étapes permettant de 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 un url qui fait référence à un tableau de bord (créé par le processus décrit sur la page de documentation de l'intégration de l'authentification unique (SSO)).

LookerEmbedSDK.createDashboardWithId(id)

ou

LookerEmbedSDK.createDashboardWithUrl(url)

Vous pouvez ensuite ajouter des attributs au compilateur pour terminer la configuration. Par exemple, vous pouvez indiquer où vous souhaitez insérer l'interface utilisateur d'intégration de Looker sur votre page Web. L'appel suivant place l'interface utilisateur d'intégration Looker dans un élément HTML avec une valeur d'ID de dashboard:

.appendTo('#dashboard')

Vous pouvez ajouter des gestionnaires d'événements:

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

Vous terminez en créant l'élément intégré:

.build()

Se connecter au contenu intégré

Si vous souhaitez envoyer des messages à l'élément intégré et recevoir des messages de l'élément intégré, vous devez appeler connect(), qui renvoie une promesse qui se résout à l'interface de communication de l'élément donné:

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

Créer des URL pour le SDK

La principale documentation concernant les URL d'intégration de l'authentification unique Looker se trouve sur la page de documentation sur l'intégration de l'authentification unique (SSO). La seule différence lorsque vous créez des URL pour le SDK est que vous devez ajouter un paramètre sdk=2 à l'URL d'intégration, en plus d'autres paramètres tels que des filtres et le paramètre embed_domain. Ce paramètre permet à Looker de déterminer si le SDK est présent et de bénéficier de fonctionnalités supplémentaires fournies par le SDK. Exemple :

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

Le SDK ne peut pas ajouter ce paramètre, car il fait partie de l'URL d'authentification unique signée.

Point de terminaison Auth

Étant donné que le secret d'intégration doit être soigneusement protégé, les URL d'intégration SSO ne peuvent pas être créées dans le navigateur. Pour faciliter et sécuriser la procédure, vous pouvez procéder comme suit:

  1. Implémentez une fonction de signature d'URL sur votre serveur Web. Le serveur doit renvoyer une URL signée à l'aide de l'un des processus décrits dans le dépôt GitHub Looker Embed SSO Examples.
  2. Transmettez l'URL d'intégration de l'authentification unique à ce point de terminaison de signature dans le SDK Embed. L'emplacement du point de terminaison est spécifié par le paramètre authUrl dans LookerEmbedSDK.init().

Si cet élément est spécifié, chaque fois qu'un élément intégré est créé à l'aide d'un ID, son URL d'intégration est générée à l'aide du type de l'élément, de l'hôte Looker fourni et des paramètres fournis. Exemple :

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

Cela appelle le point de terminaison /looker_auth et renvoie une URL SSO signée permettant de créer le contenu intégré:

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

Configuration d'authentification avancée

Vous pouvez configurer davantage le point de terminaison Auth pour autoriser les en-têtes de requêtes personnalisés et la compatibilité CORS. Pour ce faire, transmettez un objet d'options à la méthode 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
  })

Assistant de nœuds

Une méthode d'aide à la signature createSignedUrl() est fournie dans server_utils/auth_utils.ts. Son utilisation est la suivante:

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

Voici la structure des données utilisateur:

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

Le paramètre access_filters a été supprimé dans Looker 3.10, mais il est toujours obligatoire avec un espace réservé vide dans l'URL d'intégration.

Dépannage

Journalisation

Le SDK Embed s'appuie sur chatty. Chatty utilise debug 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 = ''