Notez que vous consultez la documentation Looker. Pour accéder à la documentation sur Looker Studio, consultez la page https://support.google.com/looker-studio.

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 basée sur un navigateur pour gérer les tableaux de bord, les looks et les explorations intégrés dans votre application Web. Le SDK Embed facilite l'intégration des manières suivantes:

Fournir l'encapsulation du contenu intégré sans qu'il soit nécessaire de créer manuellement des éléments HTML
Fournir une communication de type point à point pour éviter toute communication entre les cadres Le SDK Embed gère le transfert de messages interdomaines entre votre page Web hôte et votre contenu Looker intégré, à l'aide d'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 qui hébergent 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 Looker Embed est différent de l'API Looker et du SDK de l'API Looker:

Le SDK Looker Embed se trouve dans le code côté client de votre application Web et gère le contexte et le contenu de l'outil d'intégration Looker. (Le SDK Embed ne fournit pas l'accès à l'API Looker.)
L'API Looker se trouve sur le serveur avec votre instance Looker et exécute les commandes sur le serveur Looker.
Les SDK client de l'API Looker figurent 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 des événements aux applications Web. Par conséquent, l'ordre des événements n'est pas garanti dans les navigateurs ni sur les plates-formes. Veillez à écrire votre code JavaScript de façon appropriée afin de tenir compte du traitement 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, et un bouton avec l'ID run est scripté 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 documentation Démo du SDK intégré.

Configurer le SDK Looker Embed

Le SDK Looker Embed utilise un modèle d'interface fluide. Après avoir installé le SDK Embed, vous pouvez créer le contenu intégré et vous connecter 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 (NPM) à l'adresse https://www.npmjs.com/package/@looker/embed-sdk. Toutefois, si vous souhaitez voir 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 Looker Embed à l'aide du dépôt du SDK Looker Embed:

Installez Node.js, si ce n'est pas déjà fait.
Téléchargez ou clonez le dépôt /looker-open-source/embed-sdk.
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 de votre serveur Web et, éventuellement, avec le point de terminaison de votre serveur qui effectuera l'authentification. Ils sont utilisés par tout le contenu intégré.

Incluez le numéro de port si nécessaire pour accéder au serveur Looker à partir des clients du 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 sur l'intégration de l'authentification unique (SSO)).

LookerEmbedSDK.createDashboardWithId(id)

LookerEmbedSDK.createDashboardWithUrl(url)

Vous pouvez ensuite ajouter des attributs au compilateur pour terminer la configuration. Par exemple, vous pouvez spécifier où les insérer sur l'interface utilisateur de 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')

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

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

Pour terminer, créez l'élément intégré:

.build()

Se connecter au contenu intégré

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

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

Créer des URL pour le SDK

La documentation principale sur les URL d'intégration de l'authentification unique Looker se trouve dans la page de documentation sur 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 profiter des 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 lui-même, car il fait partie de l'URL d'authentification unique signée.

Le point de terminaison Auth

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

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 documentés dans le dépôt GitHub Looker Embed SSO Examples.
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()

Cette méthode 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

Le point de terminaison Auth peut être davantage configuré pour autoriser les en-têtes de requêtes personnalisés ainsi que 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'assistance à 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 repose sur chatty. Chatty utilise debug pour la journalisation. Vous pouvez activer la journalisation dans une console du 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 = ''