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.

Notez 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 blocs que vous avez installés à partir de Marketplace, consultez la page de documentation Personnaliser les blocs Marketplace.

Pour développer un bloc et le rendre accessible à tous les utilisateurs de Looker via Marketplace, procédez comme suit:

  1. Configurer la source de données et l'associer à Looker
  2. Créez un projet et ajoutez les fichiers requis.
  3. Rendez votre bloc accessible.
  4. Envoyez votre bloc pour examen 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 blocage pour un ensemble de données spécifique, tel que des données Google Analytics, notez tous les paramètres ou les personnalisations que vous avez apportés à l'ensemble de données. Dans la mesure du possible, limitez au maximum les personnalisations afin de simplifier l'installation pour vos utilisateurs. Fournissez des instructions spécifiques dans un fichier README.
  • Si vous créez un blocage en fonction d'un modèle analytique général, tel que la fidélisation des cohortes, notez les champs que l'ensemble de données de l'utilisateur doit contenir. Vos utilisateurs n'auront probablement 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 à modéliser. 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 pour chaque Explorer
  • Un fichier de modèle qui inclut tous les fichiers de vue, d'exploration et de tableau de bord LookML du projet
  • Au moins trois fichiers dans le tableau de bord LookML
  • Un fichier marketplace.json contenant les informations à afficher dans la fiche Marketplace de ce bloc
  • Un fichier LICENSE incluant le texte de la licence MIT Open Source
  • Fichier README détaillant les instructions et les options 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 doivent modifier. Par exemple, vous devez définir le nom de la connexion Looker en tant que 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 et afficher des fichiers

Créez un fichier view.lkml pour chaque vue. Si les noms de schéma et de table d'un utilisateur peuvent être différents des vôtres, 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. Référencez ensuite ces constantes dans les paramètres sql_table_name de vos vues.

Voici un exemple de fichier view.lkml de bloc:

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}
  }

}

Créez ensuite un ou plusieurs fichiers explore.lkml. Assurez-vous que chaque fichier d'exploration inclut les vues nécessaires pour cette exploration. Concevez soigneusement vos explorations pour y inclure des jointures logiques, des exercices et des pages d'exploration organisées. Une fois qu'un autre utilisateur a installé le blocage depuis Marketplace, les utilisateurs de l'entreprise doivent pouvoir facilement commencer et analyser leurs données.

Vous trouverez une liste générale des bonnes pratiques concernant la modélisation sur notre forum de la communauté et dans les bonnes pratiques Looker, comme les bonnes pratiques à éviter et à éviter, ainsi que les bonnes pratiques pour écrire un lookML durable et facile à 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"

  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 d'affichage, d'exploration et de tableau de bord de votre projet. Assurez-vous que le nom de la 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 offrant des analyses utiles et pertinentes. Les tableaux de bord doivent être complets, fonctionnels et complets. Ils ne doivent pas comporter de données floutées.

Même s'il n'existe aucune exigence stricte concernant la conception des tableaux de bord LookML, Looker recommande ces bonnes pratiques générales:

  • Palette de couleurs cohérente dans l'ensemble du tableau de bord
  • Au moins sept tuiles
  • Au moins trois types de visualisation différents (par exemple, une valeur unique, une barre et une ligne)

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

Pour en savoir plus sur la personnalisation des tableaux de bord LookML et des visualisations incluses dans les tableaux de bord LookML, consultez les pages de documentation 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 être affichée sur 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 les éléments suivants:

  • Champs label, category_label et branding de la place de marché
  • Liste de constantes LookML que les utilisateurs doivent remplir pour remplir le modèle ML (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 BigQuery 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 BigQuery 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.

Exemple de fiche Marketplace

  • Le champ "label" contrôle le titre du bloc. 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 en haut à 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'UI 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 intitulé LICENSE. Pour un exemple de fichier LICENSE, consultez le fichier LICENSE de bloc d'administration Redshift.

Créer un fichier README

Le fichier README doit contenir toutes les instructions de mise en œuvre du bloc et identifier explicitement les emplacements où les personnalisations sont nécessaires, par exemple dans le fichier manifeste généré automatiquement (#the_autogenerated_manifest_file) ou dans le fichier de référence. Consultez le fichier README de Redshift Admin Block 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 ?
  • De quels paramètres de connexion Looker avez-vous besoin ?
  • Les noms des champs de blocage correspondent-ils aux noms des champs de l'ensemble de données de l'utilisateur ? Si ce n'est pas le cas, que doit modifier votre utilisateur ?

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 sont également générés automatiquement pour votre utilisateur:

  • Un fichier marketplace_lock.lkml en lecture seule contenant des informations sur les places de marché
  • 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 fichier de modèle 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. Pour en savoir plus sur la personnalisation des blocs, consultez la page de documentation Personnaliser les blocages Looker Marketplace.

Fichier manifeste généré automatiquement

Le fichier manifeste généré automatiquement permet aux utilisateurs qui ont installé votre bloc de définir des variables telles que le nom de la connexion. Les constantes LookML définies dans le fichier manifeste de blocs peuvent être modifiées dans le fichier manifeste généré automatiquement ou définies par vos utilisateurs dans l'interface de téléchargement de blocs.

Le fichier de filtres

Le fichier refinements.lkml généré automatiquement permet aux utilisateurs qui installent votre bloc de définir des vues et des explorations pour votre bloc. C'est ici que les utilisateurs qui téléchargent votre bloc effectuent la majeure partie 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 LookML en bloc sur 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 votre blocage prêt à être envoyé, suivez les instructions de la section Envoyer du contenu à Looker Marketplace pour créer des documents justificatifs, envoyez votre blocage à l'équipe Looker pour examen, puis publiez votre blocage sur Looker Marketplace.