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 vignettes 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 Looker Extension 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 carte:

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

dashboard_vis : lorsque l'extension est activée, elle apparaît dans les options de visualisation d'une exploration, où elle peut être sélectionnée en tant que visualisation et enregistrée en tant que vignette 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 demander à la requête de carte de fournir automatiquement des données à l'extension.

Un point d'installation supplémentaire, standalone, permet d'afficher l'extension 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. Ceux-ci sont obtenus à partir du contexte de l'extension:

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

tileSDK : fournit des fonctions spécifiques aux vignettes 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. La fonction updateRowLimit en est un exemple.
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 des vignettes de tableau de bord ou des visualisations Explorer, la fenêtre de contenu de l'iFrame sera automatiquement définie sur la hauteur rendue disponible par l'iFrame.

Considérations relatives à l'affichage

Il est important de noter que les extensions de carte 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. L'exemple suivant montre comment avertir le moteur de rendu que le rendu de la carte a été effectué.

  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é)	Hébergez les données spécifiques à l'extension de carte. Consultez la section Données du SDK Tile pour en savoir plus.
`addError`	Lorsqu'ils sont appelés, le tableau de bord ou l'exploration affiche un message d'erreur sous la visualisation.
`clearError`	Lorsqu'ils sont appelés, le tableau de bord ou l'exploration masquent les messages d'erreur affichés 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 actuel ou de l'exploration.
`openScheduleDialog`	Ouvre la boîte de dialogue de planification. Cet appel est ignoré lors de l'exécution 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 du SDK de cartes disponibles sont présentées dans le tableau suivant:

Propriété	Description
`isExploring`	Lorsque la valeur est true, cela indique que la vignette est configurée en tant que visualisation à l'intérieur d'une exploration.
`dashboardId`	ID du tableau de bord de la vignette en cours de rendu. Si la vignette est configurée en tant qu'exploration, cette propriété n'est pas renseignée.
`elementId`	ID d'élément de la carte en cours de rendu. 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 vignette est configurée en tant qu'exploration, cette propriété n'est pas renseignée. `queryId` est 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`, vous devez appliquer des filtres et des filtres croisés, puis générer une nouvelle requête. Il peut donc y avoir plus de propriétés utiles que `queryId`. Consultez `filteredQuery` pour 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 qui est créé 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`, vous devez appliquer des filtres et des filtres croisés, puis générer une nouvelle requête. Par conséquent, il peut y avoir des propriétés plus 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 doit savoir avec certitude qu'un tableau de bord a été exécuté, la détection des différences dans `lastRunStartTime` est la méthode 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 ne sera 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 vignette est configurée en tant qu'exploration, cette propriété n'est pas renseignée. Notez que `lastRunSourceElementId` peut être identique à l'ID d'élément de l'instance actuelle de l'extension. 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 vignette est configurée en tant qu'exploration, cette propriété n'est 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 la dernière exécution du 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 capturer les métriques de performances.
`lastRunSuccess`	Indique si la dernière exécution du tableau de bord a réussi ou non. 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.

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: Mesurer les configurations 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 à 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 les mesures
`queryFieldDimensions`	Informations sur les dimensions
`queryFieldTableCalculations`	Informations sur le calcul de tables
`queryFieldPivots`	Informations sur le tableau croisé dynamique
`visConfig`	Données de configuration visuelle Ce paramètre 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 à la requête

Propriété	Description
`data`	Tableau de données de ligne
`fieldMeasures`	Informations de mesure de champ.
`fieldDimensions`	Informations sur les dimensions du 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.