Développer un bloc personnalisé pour Looker Marketplace

Cette page explique comment créer un bloc personnalisé pouvant être ajouté à Looker Marketplace et accessible par d'autres utilisateurs de Looker.

Veuillez noter que vous devez être membre du réseau de partenaires Looker ou client Looker pour envoyer du contenu à la place de marché Looker.

Pour en savoir plus sur les blocs Looker déjà créés et disponibles, consultez la page de documentation Blocs Looker. Pour en savoir plus sur la personnalisation des blocages que vous avez installés à partir de Marketplace, consultez la page de documentation Personnaliser les blocages de Marketplace.

Pour développer un bloc et le rendre disponible pour tous les utilisateurs de Looker sur la place de marché Looker, suivez les étapes décrites sur cette page:

  1. Configurez et connectez la source de données à Looker.
  2. Créez un projet et ajoutez les fichiers requis.
  3. Rendez votre blocage accessible.
  4. Envoyez votre bloc pour examen par Looker.

Configurer et connecter la source de données à Looker

Les blocs sont des modèles de données. Ils fonctionnent donc mieux lorsqu'ils sont conçus pour un ensemble de données spécifique et facilement reproductible. La plupart des erreurs d'installation de blocs se produisent lorsque l'ensemble de données de l'utilisateur ne correspond pas aux noms de schéma, de table et de champ du bloc.

  • Si vous créez un bloc pour un ensemble de données spécifique (les données Google Analytics, par exemple), notez tous les paramètres et toutes les personnalisations que vous avez apportés à cet ensemble de données. Dans la mesure du possible, limitez au maximum ces personnalisations afin de simplifier l'installation pour vos utilisateurs. Fournissez des instructions spécifiques dans un fichier README.
  • Si vous créez un bloc pour un modèle analytique général, comme la fidélisation des cohortes, notez les champs que l'ensemble de données de l'utilisateur doit contenir. Il est très probable que vos utilisateurs n'aient pas les mêmes noms de schéma, de table et de champ que dans votre ensemble de données. Utilisez des constantes LookML pour les noms de tables et de champs, et indiquez à l'utilisateur les champs à mettre à jour dans un fichier README.

Une fois que vous avez déterminé votre source de données, connectez-la à Looker pour commencer la modélisation. Si vous devez modifier l'un des paramètres de connexion par défaut, notez-le dans votre fichier README.

Créer un projet et ajouter les fichiers requis

Créez un projet pour représenter votre bloc. Pensez à utiliser une convention d'attribution de noms telle que
block-<database_dialect>-<role> (par exemple, block-redshift-admin).

Ensuite, créez les fichiers suivants dans votre projet:

  • Un fichier manifeste qui définit le nom du projet, le nom de la connexion et toute autre constante
  • Un fichier de vue par vue
  • Un fichier Explorer par exploration
  • Un fichier de modèle qui inclut tous les fichiers de vue et d'exploration, ainsi que les fichiers de tableau de bord LookML dans le projet
  • Au moins trois fichiers DashboardML
  • Un fichier marketplace.json contenant les informations qui seront affichées dans la fiche Marketplace de ce blocage
  • Un fichier LICENSE contenant le texte de la licence Open Source MIT
  • Fichier README détaillant les options et instructions de configuration

Les utilisateurs qui installent votre blocage peuvent affiner les explorations, les vues et les tableaux de bord de base dans un fichier refinements.lkml distinct. Les sections suivantes décrivent chaque type de fichier requis plus en détail:

Créer un fichier manifeste

Créez un fichier manifeste pour votre projet. Le fichier manifeste doit commencer par un nom de projet, puis définir des constantes LookML que vos utilisateurs devront modifier. Par exemple, vous devez définir le nom de la connexion Looker comme une constante avec export: override_required afin que les utilisateurs puissent le remplacer par leur propre nom de connexion.

Voici un exemple de fichier manifeste:

project_name: "block-ga-360"

################# Constants ################

## Used in google_analytics_block.model connection param
constant: CONNECTION_NAME {
  value: "looker-private-demo"
  export: override_required
}

## Used in ga_sessions.view sql_table_name
constant: SCHEMA_NAME {
  value: "bigquery-public-data.google_analytics_sample"
  export: override_optional
}

constant: GA360_TABLE_NAME {
  value: "ga_sessions_*"
  export: override_optional
}

Créer une vue et explorer des fichiers

Créez un fichier view.lkml pour chaque vue. Si les noms de schéma et de table d'un utilisateur peuvent différer du vôtre, veillez à définir les noms de schéma et de table comme des constantes dans votre fichier manifeste afin que les utilisateurs qui téléchargent votre bloc puissent mettre à jour les noms de schéma et de table dans le fichier manifeste généré automatiquement. Ensuite, référencez ces constantes dans les paramètres sql_table_name de vos vues.

Voici un exemple de fichier view.lkml de blocage: 

view: user_facts {

  # SCHEMA_NAME and GA360_TABLE_NAME are constants
  sql_table_name: @{SCHEMA_NAME}.@{GA360_TABLE_NAME} ;;

  dimension: clientID {
    type: string
    sql: ${TABLE.clientId}
  }

}

Ensuite, créez un ou plusieurs fichiers explore.lkml. Assurez-vous que chaque fichier d'exploration inclut les vues nécessaires. Concevez soigneusement vos explorations pour y inclure des jointures logiques, des exercices et des pages "Explorer". Une fois qu'un autre utilisateur a installé le blocage à partir de la place de marché, ses utilisateurs doivent pouvoir facilement commencer et analyser leurs données.

Vous trouverez une liste générale des bonnes pratiques de modélisation sur notre forum de la communauté et dans le Centre d'aide Looker, comme Bonnes pratiques: bonnes pratiques et astuces pour ML et Bonnes pratiques: Rédiger des modèles de ML durables et faciles à gérer.

Voici un exemple de fichier explore.lkml:

include: "/Google_Analytics/Sessions/*.view.lkml"

explore: future_input {
  view_label: "Audience Traits"
  label: "BigQuery ML Customer Likelihood to Purchase"
  description: "This explore allows you to slice and dice likeliness to purchase scores by different customer traits to see how they differ. The default range of data you are looking at is in the past 30 days"
  join: future_purchase_prediction {
    type: left_outer
    sql_on: ${future_purchase_prediction.clientId} = ${future_input.client_id} ;;
    relationship: one_to_one
  }
}

Créer un fichier de modèle

Créez un fichier de modèle qui inclut tous les fichiers de la vue, de l'exploration et du tableau de bord de votre projet. Assurez-vous que le nom de connexion est référencé en tant que constante LookML dans le fichier manifeste.

Définissez au moins un groupe de données pour définir une règle de mise en cache.

Voici un exemple de fichier de modèle:

connection: "@{CONNECTION_NAME}"

include: "/views/*.view.lkml"
include: "/explores/*.explore.lkml"
include: "/dashboards/*.dashboard.lookml"

datagroup: nightly {
  sql_trigger: SELECT TIMEZONE('US/Pacific',GETDATE())::DATE;;
}

Créer des fichiers de tableau de bord LookML

Pour être inclus dans Looker Marketplace, chaque bloc doit inclure au moins trois tableaux de bord LookML fournissant des analyses utiles et pertinentes. Les tableaux de bord doivent être complets, fonctionnels et complets. Ils ne doivent pas comporter de données floues.

Bien qu'il n'y ait aucune exigence de conception stricte pour les tableaux de bord LookML, Looker recommande ces bonnes pratiques générales de conception:

  • Palette de couleurs cohérente dans tout le tableau de bord
  • Au moins sept vignettes
  • Au moins trois types de visualisations différents (par exemple, une valeur unique, une barre et une ligne)

Les visualisations personnalisées ne sont pas acceptées lors du développement de tableaux de bord pour les blocs. Utilisez plutôt les types de visualisation natifs de Looker.

Pour en savoir plus sur la personnalisation des tableaux de bord LookML et des visualisations dans les tableaux de bord LookML, consultez les pages Paramètres du tableau de bord et Paramètres des éléments du tableau de bord. Consultez le fichier de tableau de bord LookML pour les administrateurs Redshift du bloc d'administration Redshift pour obtenir un exemple de fichier de tableau de bord LookML.

Créer un fichier marketplace.json

Créez un fichier marketplace.json pour fournir des informations sur la manière dont la fiche doit s'afficher dans Marketplace. Chaque bloc de Looker Marketplace doit fournir ces informations supplémentaires pour aider les utilisateurs à sélectionner le bloc qui répond le mieux à leurs besoins. Votre fichier marketplace.json doit contenir:

  • Champs label, category_label et branding de la place de marché
  • Liste de constantes LookML que les utilisateurs doivent remplir pour remplir le LookML du modèle (par exemple, les noms de connexion)

Voici un exemple de fichier marketplace.json pour le bloc de performances Google BigQuery:

{
  "label": "Google BigQuery Performance",
  "category_label": "Models",
  "branding": {
    "image_uri": "https://marketplace-api.looker.com/block-icons/google-cloud.png",
    "tagline": "This Block provides a comprehensive overview of all cost and performance data for one or multiple BQ projects, enabling users to effectively monitor BigQuery usage down to a per user level. It can be used to set up alerts to long running or high cost queries."
  },

  "constants": {
    "CONNECTION_NAME": {
      "label": "Connection Name",
      "value_constraint": "connection"
    },
    "SCHEMA_NAME": {
      "label": "Schema Name"
    },
    "AUDIT_LOG_EXPORT_TABLE_NAME": {
      "label": "Audit Log Export Table Name",
      "description": "The table name of your BQ Optimization data (typically cloudaudit_googleapis_com_data_access_*)."
    }
  },
  "models": [
    {
      "name": "block_bigquery_optimization_v2",
      "connection_constant": "CONNECTION_NAME"
    }
  ]
}

La capture d'écran suivante montre la fiche Marketplace générée par ce fichier marketplace.json.

  • Le champ "label" contrôle le titre du blocage. Dans cet exemple, il s'agit de Google BigQuery Performance.
  • Le champ "tagline" contrôle le premier paragraphe de la fiche Marketplace.
  • Le champ "image_uri" contrôle l'image affichée dans l'angle supérieur gauche de la fiche Marketplace. Dans cet exemple, il s'agit du logo Google Cloud.
  • Le champ "constants" invite les utilisateurs à renseigner leurs constantes dans l'interface utilisateur de Marketplace pendant le processus d'installation. Dans cet exemple, trois constantes sont listées dans le fichier marketplace.json (CONNECTION_NAME, SCHEMA_NAME et AUDIT_LOG_EXPORT_TABLE_NAME). L'utilisateur sera donc invité à spécifier des valeurs pour ces trois champs avant l'installation.

Créer un fichier LICENSE

Tous les blocs Looker doivent être concédés sous licence MIT Open Source. Incluez le texte de cette licence dans un fichier nommé LICENSE. Consultez le fichier LICENSE de bloc d'administration Redshift pour obtenir un exemple de fichier LICENSE.

Créer un fichier README

Le fichier README doit contenir toutes les instructions de mise en œuvre du bloc et identifier explicitement les éventuelles personnalisations requises, comme dans le fichier manifeste généré automatiquement (#the_autogenerated_manifest_file) ou dans le fichier de références. Consultez le fichier README du blocage de l'administrateur Redshift pour obtenir un exemple de fichier README.

Éléments à prendre en compte pour votre fichier README:

  • De quelle source de données l'utilisateur a-t-il besoin ? Doit-il payer pour souscrire un abonnement ?
  • Quelles autorisations l'utilisateur de la base de données doit-il avoir ?
  • Quels paramètres de connexion Looker sont nécessaires ?
  • Les noms de champs de blocs correspondent-ils aux noms de champs de votre ensemble de données d'utilisateur ? Si ce n'est pas le cas, que doit-il modifier ?

Fichiers générés automatiquement

Lorsque les utilisateurs installent votre bloc, leur instance Looker crée un projet Looker avec les fichiers de votre projet en tant que fichiers en lecture seule. Les fichiers suivants seront également générés automatiquement pour votre utilisateur:

  • Un fichier marketplace_lock.lkml en lecture seule contenant des informations sur les fiches Marketplace
  • Fichier manifeste faisant référence à la fiche de marketplace_lock.lkml
  • Un fichier refinements.lkml qui inclut toutes les vues et explorations de votre bloc
  • Un modèle de fichier en lecture seule incluant à la fois le fichier de modèle de votre bloc et le fichier refinements.lkml

Les utilisateurs qui installent votre bloc depuis Looker Marketplace peuvent utiliser le fichier refinements.lkml pour affiner votre LookML et même ajouter de nouveaux fichiers LookML. Consultez la page de documentation Personnaliser des blocages sur Marketplace pour savoir comment les utilisateurs peuvent personnaliser votre blocage.

Fichier manifeste généré automatiquement

Le fichier manifeste généré automatiquement permet aux utilisateurs qui installent votre bloc de définir des variables telles que le nom de connexion. Les constantes LookML définies dans le fichier manifeste de blocage peuvent être modifiées dans le fichier manifeste de génération automatique, ou définies par vos utilisateurs dans l'interface utilisateur de téléchargement en mode bloc.

Fichier des filtres

Le fichier refinements.lkml généré automatiquement permet aux utilisateurs qui installent votre blocage d'affiner les vues et les explorations définies pour votre blocage. C'est là que les utilisateurs qui téléchargent votre blocage effectueront l'essentiel de la personnalisation de LookML en fonction de leur cas d'utilisation.

Voici un exemple de fichier refinements.lkml généré automatiquement:

include: "//ga360-v2/**/*.view.lkml"
include: "//ga360-v2/**/*.explore.lkml"

\# Use LookML refinements to refine views and explores that are defined in the remote project.
\# Learn more at: https://docs.looker.com/data-modeling/learning-lookml/refinements
\#
\#
\# For example we could add a new dimension to a view:
\#     view: +flights {
\#       dimension: air_carrier {
\#         type: string
\#         sql: ${TABLE}.air_carrier ;;
\#       }
\#     }
\#
\# Or apply a label to an explore:
\#     explore: +aircraft {
\#       label: "Aircraft Simplified"
\#     }
\#

Rendre le projet de bloc accessible

Hébergez votre bloc LookML dans un dépôt GitHub public.

Tous les blocs Looker doivent être concédés sous licence MIT Open Source, et le texte de la licence doit être inclus dans un fichier LICENSE dans le dépôt.

Envoi du blocage pour examen

Une fois que votre blocage est prêt à être envoyé, suivez les instructions de la section Envoyer du contenu à Looker Marketplace afin de créer des documents justificatifs pour votre blocage, envoyez votre blocage à l'équipe Looker pour examen et publiez votre blocage sur Looker Marketplace.