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

Cette page a été traduite par l'API Cloud Translation.

Présentation du SDK d'ingestion

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 présentations et les explorations intégrés dans votre application Web. Le SDK Embed facilite l'intégration de différentes manières:

Fournit l'encapsulation du contenu intégré sans avoir à créer manuellement des éléments HTML.
Fournit une communication point à point afin d'éviter toute 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 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 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 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 des commandes sur le serveur Looker.
Les SDK clients de l'API Looker résident dans le code des applications autres que des navigateurs 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 l'ensemble des navigateurs ou des 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

Cet exemple crée un contexte d'intégration Looker, l'insère dans un élément DOM avec un ID de dashboard, puis affiche un tableau de bord avec un ID de 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 dont l'ID est run est rédigé 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)
  })

Un exemple plus complet est décrit sur la page de documentation Démonstration du SDK Embed.

Configurer le SDK d'intégration de 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.

Installer le SDK Embed

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 Looker Embed à l'aide du dépôt:

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, le point de terminaison de votre serveur qui effectuera l'authentification. Ceux-ci sont utilisés par tout le contenu intégré.

Indiquez le numéro de port si vous devez accéder au serveur Looker à partir de 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 pour définir ses paramètres. Certains de ces paramètres sont facultatifs, d'autres obligatoires.

Le processus commence par la création du compilateur, soit avec un id de tableau de bord, soit 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).

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

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 par créer l'élément intégré :

.build()

Connexion 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 se résout en interface de communication de l'élément donné :

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

Créer des URL pour le SDK

La principale documentation sur les URL d'intégration signée Looker se trouve sur la page Intégration signée. La seule différence réside dans le fait que vous devez ajouter un paramètre sdk=2 à l'URL d'intégration avec d'autres paramètres, tels que des filtres et le paramètre embed_domain. Ce paramètre permet à Looker de déterminer que le SDK est présent et de profiter 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.

Point de terminaison d'autorisation

É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 rendre le processus plus simple et plus sécurisé, vous pouvez plutôt suivre ces étapes:

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 Exemples de SSO Looker Embed.
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 LookerEmbedSDK.init().

Si vous le spécifiez, chaque fois qu'un élément intégré est créé à l'aide d'un seul 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 de tous les 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 pouvant être utilisée pour 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 d'authentification peut être configuré davantage pour autoriser les en-têtes de requêtes personnalisés et la compatibilité avec 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
  })

Aide de nœud

Une méthode d'assistance de signature createSignedUrl() est fournie dans server_utils/auth_utils.ts. Voici son utilisation:

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 d'ingestion est basé sur chatty. Chatty utilise le débogage pour la journalisation. Vous pouvez activer la journalisation dans la 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 = ''