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

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

Présentation du SDK d'ingestion

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 looks et les explorations intégrés dans votre application Web. Le SDK d'intégration facilite l'intégration de la manière suivante:

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 à l'aide d'é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 d'intégration Looker est différent de l'API Looker et du SDK de l'API Looker:

Le SDK d'ingestion Looker se trouve dans le code côté client de votre application Web et gère le contexte et le contenu d'ingestion 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 se trouvent dans le code des applications autres que les navigateurs pour faciliter l'accès aux fonctions de l'API Looker.

Notez 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 entre les navigateurs et les 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'UI de la fenêtre d'intégration. Un bouton avec un ID de run est programmé 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 de la démo du SDK d'intégration.

Configurer le SDK d'ingestion 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 d'ingestion

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

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. Ils sont utilisés par l'ensemble du 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 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 générateur pour terminer la 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()

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 se résout en tant qu'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 Inclusion intégrée signée. 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, ainsi que d'autres paramètres, tels que les 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 est impossible de créer des URL d'intégration signées dans le navigateur. Pour simplifier et sécuriser le processus, vous pouvez plutôt suivre ces étapes:

Implémentez une fonction de signature d'URL dans 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'ingestion signée à ce point de terminaison de signature dans le SDK d'intégration. 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 d'intégration 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é plus en détail pour autoriser les en-têtes de requête personnalisés et la prise en charge de 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œud

Une méthode d'assistance de 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 d'ingestion est basé sur 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 = ''