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.

Créer des extensions de carte

À partir de la version 24.0 de Looker, vous pouvez développer des extensions à exécuter dans une carte de tableau de bord. Les extensions qui peuvent être exécutées en tant que vignette ou visualisation peuvent être ajoutées lorsque le tableau de bord est en mode Édition ou enregistrées dans un tableau de bord en tant que visualisation à partir d'une exploration. Les extensions peuvent également être configurées en tant que cartes dans les tableaux de bord LookML.

Voici des exemples d'extensions pouvant être utilisées comme cartes de tableau de bord :

L'extension de visualisation des cartes montre comment créer une visualisation personnalisée à l'aide du framework d'extension.
L'extension du SDK Tile affiche les méthodes d'API disponibles spécifiques aux extensions de cartes.

Utiliser le SDK de l'extension Looker avec des extensions de carte

Pour que les extensions de carte soient chargées en tant que cartes dans un tableau de bord, le paramètre mount_points doit être défini dans le fichier manifeste du projet LookML. Il existe deux types de mount_points liés aux extensions de cartes :

  mount_points: {
    dashboard_vis: yes
    dashboard_tile: yes
    standalone: yes
  }

dashboard_vis : lorsque cette option est activée, l'extension s'affiche dans les options de visualisation d'une exploration, où elle peut être sélectionnée comme visualisation et enregistrée en tant que carte de tableau de bord. Lorsque le tableau de bord est exécuté, il exécute la requête associée à la vignette et met les données à la disposition de l'extension. Ce fonctionnement est semblable à celui des visualisations personnalisées. La principale différence entre une visualisation personnalisée et une extension exécutée dans une vignette de tableau de bord pour laquelle dashboard_vis est activé est que l'extension peut effectuer des appels de l'API Looker.
dashboard_tile : lorsque cette option est activée, l'extension apparaît dans le panneau Extensions qui s'affiche lorsqu'un utilisateur modifie un tableau de bord et sélectionne l'option Extensions après avoir cliqué sur le bouton Ajouter. Ce type d'extension est chargé de récupérer ses propres données, au lieu de laisser la requête de carte fournir automatiquement des données à l'extension.

Un point d'installation supplémentaire, standalone, permet à l'extension d'apparaître dans la section Applications du menu principal de Looker. Il est possible qu'une extension comporte plusieurs points d'installation définis. Au moment de l'exécution, l'extension est informée de son installation et peut ajuster son comportement en conséquence. Par exemple, les extensions standalone peuvent avoir besoin de définir leur propre hauteur, contrairement aux extensions de carte.

API supplémentaires pour les extensions de cartes

Les extensions de cartes sont fournies avec des API et des données supplémentaires au moment de l'exécution. Ils sont obtenus à partir du contexte de l'extension :

const {
  tileSDK,
  tileHostData,
  visualizationData,
  visualizationSDK,
} = useContext(ExtensionContext40)

tileSDK : fournit des fonctions spécifiques aux cartes pour permettre à l'extension d'interagir avec l'hôte du tableau de bord Looker. Par exemple, pour autoriser l'extension à afficher et effacer les messages d'erreur.
tileHostData : fournit des données de carte à l'extension. Les données sont automatiquement mises à jour en fonction des interactions avec le tableau de bord d'hébergement. L'indicateur isDashboardEditing en est un bon exemple.
visualizationSDK : fournit des fonctions spécifiques à la visualisation pour permettre à l'extension d'interagir avec l'hôte du tableau de bord Looker. C'est le cas de la fonction updateRowLimit.
visualizationData : fournit des données de visualisation à l'extension. Les données sont automatiquement mises à jour en fonction des interactions avec le tableau de bord d'hébergement. Les données sont semblables à celles fournies aux visualisations personnalisées.

Créer des extensions réactives

Les iFrames dans lesquels les extensions s'exécutent sont automatiquement redimensionnés à mesure que la fenêtre de l'hôte Looker parent est redimensionnée. Cela se reflète automatiquement dans la fenêtre de contenu de l'iFrame. Le composant iframe n'a pas de marge intérieure ni de marge. Il appartient donc à l'extension de fournir ses propres marges afin d'assurer une cohérence avec l'application Looker. Pour les extensions autonomes, c'est à l'extension de contrôler sa hauteur. Pour les extensions exécutées dans les cartes de tableau de bord ou les visualisations d'exploration, la fenêtre de contenu de l'iframe est automatiquement définie sur la hauteur disponible par l'iframe.

Considérations relatives à l'affichage

Il est important de noter que les extensions de vignette s'affichent lorsqu'un tableau de bord est téléchargé sous forme de PDF ou d'image. Le moteur de rendu s'attend à ce que la carte l'informe une fois le rendu terminé. Sinon, le moteur de rendu cessera de répondre. Voici un exemple de notification au moteur de rendu que la carte a été affichée.

  const { extensionSDK } = useContext(ExtensionContext40)

  useEffect(() => {
    extensionSDK.rendered()
  }, [])

Les animations doivent également être désactivées lors du rendu. Voici un exemple dans lequel les configurations d'animation sont désactivées lors de l'affichage:

  const { lookerHostData} = useContext(ExtensionContext40)
  const isRendering = lookerHostData?.isRendering

  const config = isRendering
    ? {
        ...visConfig,
        valueCountUp: false,
        waveAnimateTime: 0,
        waveRiseTime: 0,
        waveAnimate: false,
        waveRise: false,
      }
    : visConfig

  if (mountPoint === MountPoint.dashboardVisualization) {
    return <VisualizationTile config={config} />
  }

Fonctions et propriétés du SDK Tile

Le SDK de cartes fournit des fonctions qui permettent à une extension de carte d'interagir avec son tableau de bord d'hébergement.

Les fonctions et propriétés disponibles sont présentées dans le tableau suivant:

Fonction ou propriété	Description
`tileHostData` (propriété)	Données hôte spécifiques à l'extension de tuile. Pour en savoir plus, consultez la section Données du SDK Tile.
`addError`	Lorsqu'ils sont appelés, le tableau de bord ou l'exploration affichent un message d'erreur sous la visualisation.
`clearError`	Lorsqu'il est appelé, le tableau de bord ou l'exploration masque tout message d'erreur affiché sous la visualisation.
`openDrillMenu`	Pour les extensions de visualisation, cet appel ouvre un menu d'analyse. Cet appel est ignoré si l'extension n'est pas une visualisation d'extension de carte.
`runDashboard`	Exécute le tableau de bord actuel. Cet appel est ignoré par une extension de visualisation de cartes exécutée dans une exploration.
`stopDashboard`	Arrête un tableau de bord en cours d'exécution. Cet appel est ignoré par une extension de visualisation de cartes exécutée dans une exploration.
`updateFilters`	Met à jour les filtres du tableau de bord ou de l'exploration en cours.
`openScheduleDialog`	Ouvre la boîte de dialogue de planification. Cet appel est ignoré lorsqu'il s'exécute dans une exploration.
`toggleCrossFilter`	Active/Désactive les filtres croisés. Cet appel est ignoré lorsqu'il s'exécute dans une exploration.

Données du SDK Tile

Les propriétés des données disponibles du SDK de cartes sont présentées dans le tableau suivant:

Propriété	Description
`isExploring`	Si cette valeur est définie sur "true", cela signifie que la carte est configurée en tant que visualisation dans une exploration.
`dashboardId`	ID du tableau de bord de la vignette en cours de rendu. Si la carte est configurée en tant qu'exploration, cette propriété ne sera pas renseignée.
`elementId`	ID de l'élément de la carte affichée. Si la vignette est configurée en tant qu'exploration, cette propriété n'est pas renseignée.
`queryId`	ID de requête de la carte en cours de rendu si elle est associée à une visualisation. Si la carte est configurée en tant qu'exploration, cette propriété ne sera pas renseignée. `queryId` correspond à l'ID de la requête créée lorsque la visualisation est intégrée à l'exploration Looker. Il ne contient aucun filtre ni filtrage croisé à appliquer au tableau de bord. Pour refléter les données affichées dans `QueryResponse`, des filtres et des filtres croisés doivent être appliqués, et une nouvelle requête doit être générée. Il peut donc y avoir plus de propriétés utiles que `queryId`. Consultez la section `filteredQuery` pour obtenir un objet de requête avec des filtres appliqués.
`querySlug`	slug de la requête de la vignette affichée si elle est associée à une visualisation. Si la vignette est configurée en tant qu'exploration, cette propriété n'est pas renseignée. `querySlug` est un slug de la requête créée lorsque la visualisation est intégrée à l'exploration Looker. Il ne contient aucun filtre ni filtrage croisé appliqué au tableau de bord. Pour refléter les données affichées dans `QueryResponse`, des filtres et des filtres croisés doivent être appliqués, et une nouvelle requête doit être générée. Il peut donc y avoir plus de propriétés utiles que `querySlug`. Consultez la section `filteredQuery` pour obtenir un objet de requête avec des filtres appliqués.
`dashboardFilters`	Filtres appliqués au tableau de bord. Si la vignette est configurée en tant qu'exploration, cette propriété n'est pas renseignée.
`dashboardRunState`	Indique si le tableau de bord est en cours d'exécution. Si la carte est configurée en tant qu'exploration, l'état sera `UNKNOWN`. Pour des raisons de performances du tableau de bord, l'état d'exécution peut ne jamais apparaître comme étant en cours d'exécution. Cela se produit généralement si aucune autre tuile n'est associée à une requête, y compris celle à laquelle l'extension est associée. Si l'extension a besoin de savoir avec certitude qu'un tableau de bord a été exécuté, la détection des différences au niveau de `lastRunStartTime` est la méthode la plus fiable.
`isDashboardEditing`	Si la valeur est "true", le tableau de bord est en cours de modification. Si la carte est configurée en tant qu'exploration, cette propriété ne sera pas renseignée.
`isDashboardCrossFilteringEnabled`	Lorsque cette option est définie sur "true", le filtrage croisé est activé sur le tableau de bord. Si la carte est configurée en tant qu'exploration, cette propriété ne sera pas renseignée.
`filteredQuery`	Objet de requête correspondant à l'ID de requête associé à l'élément de tableau de bord sous-jacent qui applique les filtres du tableau de bord et les modifications de fuseau horaire effectuées au niveau du tableau de bord.
`lastRunSourceElementId`	ID de l'élément d'extension de carte ayant déclenché la dernière exécution du tableau de bord. L'ID n'est pas défini si l'exécution du tableau de bord a été déclenchée par le bouton Exécuter ou l'autorefresh du tableau de bord, ou si l'exécution a été déclenchée à l'aide du SDK d'intégration. Si la carte est configurée en tant qu'exploration, cette propriété ne sera pas renseignée. Notez que `lastRunSourceElementId` peut être identique à l'ID de l'élément de l'instance d'extension actuelle. Par exemple, si l'extension déclenche l'exécution d'un tableau de bord, elle sera avertie lorsque l'exécution du tableau de bord commencera et se terminera.
`lastRunStartTime`	Indique l'heure de début de la dernière exécution du tableau de bord. Si la carte est configurée en tant qu'exploration, cette propriété ne sera pas renseignée. Notez que les heures de début et de fin indiquées ne doivent pas être utilisées pour capturer les métriques de performances.
`lastRunEndTime`	Indique l'heure de fin de l'exécution du dernier tableau de bord. Si la vignette est configurée en tant qu'exploration, cette propriété n'est pas renseignée. Si la carte est en cours d'exécution, cette propriété ne sera pas renseignée. Notez que les heures de début et de fin indiquées ne doivent pas être utilisées pour collecter les métriques de performances.
`lastRunSuccess`	Indique si l'exécution du dernier tableau de bord a réussi ou non. Si la carte est configurée en tant qu'exploration, cette propriété ne sera pas renseignée. Si la carte est en cours d'exécution, cette propriété ne sera pas renseignée.

Fonctions et propriétés du SDK de visualisation

Les fonctions et propriétés du SDK de visualisation disponibles sont présentées dans le tableau suivant:

Fonction ou propriété	Description
`visualizationData` (propriété)	Visualisation (combinaison de données `visConfig` et `queryResponse`).
`visConfig` (propriété)	Données de configuration de la visualisation: Configurations de mesure Configurations des dimensions Calculs de tables Configurations de pivot Configurations de visualisation Ils permettent de personnaliser l'apparence d'une visualisation dans une exploration.
`queryResponse` (propriété)	Données de réponse de la requête
`configureVisualization`	Définit la configuration par défaut d'une visualisation d'extension. La configuration est affichée dans l'éditeur de visualisation des explorations. Cette méthode ne doit être appelée qu'une seule fois.
`setVisConfig`	Met à jour la configuration de la visualisation.
`updateRowLimit`	Met à jour la limite de lignes de la requête.

Données du SDK de visualisation

Le SDK de visualisation se compose des éléments suivants :

Données de configuration de la visualisation
Données de réponse à la requête

Données de configuration de la visualisation

Propriété	Description
`queryFieldMeasures`	Informations sur la mesure
`queryFieldDimensions`	Informations sur la dimension
`queryFieldTableCalculations`	Informations sur les calculs de table
`queryFieldPivots`	Informations sur le pivot
`visConfig`	Données de configuration visuelle. Il doit être fusionné avec la configuration par défaut et appliqué à la visualisation affichée par l'extension.

export interface VisualizationConfig {
  queryFieldMeasures: Measure[]
  queryFieldDimensions: Dimension[]
  queryFieldTableCalculations: TableCalculation[]
  queryFieldPivots: PivotConfig[]
  visConfig: RawVisConfig
}

Données de réponse des requêtes

Propriété	Description
`data`	Tableau de données de ligne
`fieldMeasures`	Informations sur la mesure du champ.
`fieldDimensions`	Informations sur la dimension de champ.
`fieldTableCalculations`	Informations sur les calculs de tables de champ.
`fieldPivots`	Informations sur le tableau croisé dynamique des champs
`fieldMeasureLike`	Tableau concaténé d'informations de mesure de champ et de calculs de table qui se comportent comme des mesures.
`fieldDimensionLike`	Tableau concaténé d'informations de dimension de champ et de calculs de table qui se comportent comme des dimensions.