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, Looks et 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 avoir à créer manuellement des éléments HTML
Fournir une communication point à point afin qu'il n'y ait pas de communication entre les cadres. Le SDK Embed gère les 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 du contenu Looker intégré ou y répondre à l'aide d'événements JavaScript tels que dashboard:run:start ou page:changed, décrits dans 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 utiliser les événements de diffusion de fenêtres pour les communications entre l'application Web et le contenu intégré.

Notez que le SDK Embed de Looker 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'intégration 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 résident dans le code des applications autres qu'un navigateur pour 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 à écrire votre code JavaScript de façon appropriée pour prendre en compte la gestion des événements de 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 un 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 dont l'ID est 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émonstration du SDK Embed.

Configurer le SDK Looker Embed

Le SDK Looker Embed utilise un modèle d'interface fluide. Une fois que vous avez installé le SDK Embed, vous devez construire le contenu intégré et vous y connecter.

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 voulez 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:

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

Construire le contenu intégré

Commencez par initialiser le SDK avec l'adresse de votre serveur Web et, éventuellement, le point de terminaison de votre serveur qui effectuera l'authentification. Ceux-ci sont utilisés par l'ensemble du contenu intégré.

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

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

Ensuite, le contenu intégré est créé selon 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).

LookerEmbedSDK.createDashboardWithId(id)

LookerEmbedSDK.createDashboardWithUrl(url)

Vous pouvez ensuite ajouter d'autres attributs au compilateur pour terminer votre configuration. Par exemple, vous pouvez spécifier l'emplacement où insérer l'interface utilisateur intégrée de Looker sur votre page Web. L'appel suivant place l'UI intégrée de 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 voulez envoyer et recevoir des messages depuis l'élément intégré, 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 signées Looker se trouve sur la page de documentation Intégration signée. Lorsque vous créez des URL pour le SDK, la seule différence est que vous devez ajouter un paramètre sdk=2 à l'URL d'intégration avec d'autres paramètres, comme les filtres et le paramètre embed_domain. Ce paramètre permet à Looker de déterminer que le SDK est présent et de tirer parti des fonctionnalités supplémentaires qu'il fournit. 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'intégration signée.

Le point de terminaison de l'authentification

Étant donné que le secret d'intégration doit être soigneusement protégé, il n'est pas possible de créer des URL d'intégration signées dans le navigateur. Pour faciliter et sécuriser ce processus, nous vous invitons à procéder comme suit:

Mettez en œuvre 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 Exemples d'authentification unique intégrée à Looker.
Transmettez l'URL d'intégration signée à 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 le fichier LookerEmbedSDK.init().

Si une valeur est spécifiée, chaque fois qu'un élément intégré est créé à l'aide d'un simple 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()

L'exemple précédent appelle le point de terminaison /looker_auth et renvoie une URL d'intégration 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 avancée de l'authentification

Vous pouvez configurer davantage le point de terminaison d'authentification pour autoriser les en-têtes de requêtes personnalisés et la compatibilité avec le 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
  })

Outil d'aide pour les 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 le 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 = ''