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

Créer des extensions de tuiles

À partir de la version 24.0 de Looker, vous pouvez développer des extensions à exécuter dans une carte de tableau de bord. Vous pouvez ajouter des extensions pouvant être exécutées en tant que vignette ou visualisation lorsque le tableau de bord est en mode Édition ou les enregistrer 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 de carte affiche les méthodes d'API disponibles qui sont spécifiques aux extensions de carte.

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 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 carte et met les données à la disposition de l'extension. Ce mode de 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 carte de tableau de bord pour laquelle dashboard_vis est activé est que l'extension peut effectuer des appels à l'API Looker.
dashboard_tile : lorsque l'extension est activée, elle s'affiche 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 avertie de la façon dont elle est montée et peut ajuster son comportement en conséquence. Par exemple, les extensions standalone peuvent devoir définir leur propre hauteur, contrairement aux extensions de carte.

API supplémentaires pour l'extension de tuiles

Les extensions de carte 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 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 lorsque la fenêtre hôte Looker parente est redimensionnée. Cela est automatiquement reflété dans la fenêtre de contenu de l'iframe. Le composant iframe ne comporte aucune marge intérieure ni marge extérieure. Il revient donc à l'extension de fournir sa propre marge intérieure et sa propre marge extérieure afin qu'elle soit cohérente avec l'application Looker. Pour les extensions autonomes, c'est l'extension qui contrôle la hauteur de l'extension. 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.

Remarques concernant le rendu

Notez que les extensions de cartes s'affichent lorsque vous téléchargez un tableau de bord au format PDF ou image. Le moteur de rendu s'attend à ce que la carte l'informe lorsque le rendu est 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 où les configurations d'animation sont désactivées lors du rendu:

  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 carte 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 indiqué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'il est appelé, le tableau de bord ou Exploration affiche 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 de données du SDK de carte disponibles sont indiqué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 carte affichée. 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 carte est configurée en tant qu'exploration, cette propriété ne sera pas renseignée.
`queryId`	ID de la requête de la carte affichée 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 `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 carte est configurée en tant qu'exploration, cette propriété ne sera 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 `filteredQuery` pour un objet de requête avec des filtres appliqués.
`dashboardFilters`	Filtres appliqués au tableau de bord. Si la carte est configurée en tant qu'exploration, cette propriété ne sera 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, son état est `UNKNOWN`. Pour des raisons de performances du tableau de bord, l'état d'exécution peut ne jamais être affiché comme en cours d'exécution. Cela se produit généralement s'il n'y a pas d'autres cartes associées à 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`	Si cette valeur est définie sur "true", le filtrage croisé est activé dans 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 est indéfini si l'exécution du tableau de bord a été déclenchée par le bouton Run (Exécuter) ou par la mise à jour automatique 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 en sera informée au début et à la fin de l'exécution.
`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 collecter des métriques de performances.
`lastRunEndTime`	Indique l'heure de fin de l'exécution du dernier tableau de bord. 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é n'est pas renseignée. Notez que les heures de début et de fin indiquées ne doivent pas être utilisées pour collecter des 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é n'est pas renseignée.

Fonctions et propriétés du SDK de visualisation

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

Fonction ou propriété	Description
`visualizationData` (propriété)	Visualisation (combinaison des 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 tableaux croisés dynamiques 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 s'affichera dans l'éditeur de visualisation Explorer. 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 des requêtes

Données de configuration de la visualisation

Propriété	Description
`queryFieldMeasures`	Informations sur la mesure
`queryFieldDimensions`	Informations sur la dimension
`queryFieldTableCalculations`	Informations sur le calcul 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 table de champ.
`fieldPivots`	Informations sur le pivot de champ.
`fieldMeasureLike`	Tableau concaténé d'informations sur les mesures de champ et de calculs de table qui se comportent comme des mesures.
`fieldDimensionLike`	Tableau concaténé d'informations sur les dimensions de champ et de calculs de table qui se comportent comme des dimensions.

Utiliser le SDK d'ingestion

L'utilisation du SDK Embed dans une extension de carte n'est pas recommandée pour les raisons suivantes:

Il est possible que l'extension affiche un tableau de bord dans lequel elle est une carte. Le framework d'extension n'a aucun moyen de le détecter. Par conséquent, le navigateur risque de planter.
Le rendu PDF du contenu intégré dans une extension de carte ne fonctionne pas.