Desarrollar un bloque personalizado para Looker Marketplace

En esta página se describe cómo crear un bloque personalizado que se puede añadir a Looker Marketplace y al que pueden acceder otros usuarios de Looker.

Ten en cuenta que debes ser miembro de la red de partners de Looker o cliente de Looker para enviar contenido a Looker Marketplace.

Para obtener información sobre los bloques de Looker que ya están creados y disponibles, consulta la página de documentación Bloques de Looker. Para obtener información sobre cómo personalizar los bloques que ha instalado desde Marketplace, consulte la página de documentación Personalizar bloques de Looker Marketplace.

Para desarrollar un bloque y ponerlo a disposición de todos los usuarios de Looker a través de Looker Marketplace, sigue los pasos que se describen en esta página:

  1. Configura y conecta la fuente de datos a Looker.
  2. Crea un proyecto y añade los archivos necesarios.
  3. Haz que tu bloque sea accesible.
  4. Envía tu bloque para que lo revise Looker.

Configurar y conectar la fuente de datos a Looker

Los bloques son modelos de datos, por lo que funcionan mejor cuando se diseñan para un conjunto de datos específico y fácilmente repetible. La mayoría de los errores de instalación de bloques se producen cuando el conjunto de datos del usuario no coincide con los nombres de esquema, tabla y campo del bloque.

  • Si va a crear un bloque para un conjunto de datos específico, como datos de Google Analytics, anote los ajustes o las personalizaciones que haya hecho en el conjunto de datos. Cuando sea posible, reduce al mínimo estas personalizaciones para simplificar la instalación a tus usuarios. Proporciona instrucciones específicas en un archivo README.
  • Si vas a crear un bloque para un patrón analítico general, como la retención de cohortes, anota los campos que quieres que contenga el conjunto de datos del usuario. Lo más probable es que los usuarios no tengan los mismos nombres de esquema, tabla y campo que en tu conjunto de datos. Usa constantes de LookML para los nombres de las tablas y los campos, e informa a los usuarios de qué campos deben actualizar en un archivo README.

Una vez que hayas determinado tu fuente de datos, conéctala a Looker para empezar a modelizar. Si necesitas cambiar alguno de los ajustes de conexión predeterminados, anótalo en el archivo README.

Crear un proyecto y añadir los archivos necesarios

Crea un proyecto que represente tu bloque. Te recomendamos que utilices una convención de nomenclatura como block-<database_dialect>-<role> (por ejemplo, block-redshift-admin).

A continuación, crea los siguientes archivos en tu proyecto:

  • Un archivo de manifiesto que define el nombre del proyecto, el nombre de la conexión y cualquier otra constante
  • Un archivo de vista para cada vista
  • Un archivo de exploración por cada Exploración
  • Un archivo de modelo que incluye todos los archivos de vista, de exploración y de panel de control de LookML del proyecto
  • Al menos tres archivos de panel de control de LookML
  • Un archivo marketplace.json que contiene información que se mostrará en la ficha de Marketplace de este bloque
  • Un archivo LICENSE que incluya el texto de la licencia de software libre MIT
  • Un archivo README con instrucciones y opciones de configuración detalladas

Los usuarios que instalen tu bloque pueden refinar las exploraciones, las vistas y los paneles de control básicos en un archivo refinements.lkml independiente. En las siguientes secciones se explica cada tipo de archivo obligatorio con más detalle:

Crear un archivo de manifiesto

Crea un archivo de manifiesto para tu proyecto. El archivo de manifiesto debe empezar con un nombre de proyecto y, a continuación, definir algunas constantes de LookML para que los usuarios puedan cambiarlas. Por ejemplo, debes definir el nombre de la conexión de Looker como una constante con export: override_required para que los usuarios puedan sustituirlo por el nombre de su propia conexión.

Aquí tienes un archivo de manifiesto de ejemplo:

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
}

Crear archivos de vista y exploración

Crea un archivo view.lkml para cada vista. Si los nombres de esquema y de tabla de un usuario pueden ser diferentes de los tuyos, define los nombres de esquema y de tabla como constantes en tu archivo de manifiesto para que los usuarios que descarguen tu bloque puedan actualizar los nombres de esquema y de tabla en el archivo de manifiesto generado automáticamente. A continuación, haz referencia a esas constantes en los parámetros sql_table_name de tus vistas.

A continuación, se muestra un ejemplo de archivo de bloque view.lkml:

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

}

A continuación, crea uno o varios archivos explore.lkml. Asegúrate de que cada archivo de Exploración incluya las vistas necesarias para esa exploración. Diseña tus Exploraciones de forma que contengan combinaciones lógicas, desgloses y páginas de Exploración seleccionadas. Cuando otro usuario instale el bloque desde Marketplace, los usuarios de su empresa podrán empezar a analizar sus datos fácilmente.

Puedes consultar una lista general de prácticas recomendadas de modelización en nuestro foro de la comunidad y en las prácticas recomendadas de Looker, como Prácticas recomendadas: qué hacer y qué no hacer con LookML y Prácticas recomendadas: escribir código LookML sostenible y fácil de mantener.

A continuación, se muestra un ejemplo de archivo 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
  }
}

Crear un archivo de modelo

Crea un archivo de modelo que incluya todos los archivos de vistas, exploraciones y paneles de tu proyecto. Asegúrate de que el nombre de la conexión se haga referencia como una constante de LookML desde tu archivo de manifiesto.

Define al menos un grupo de datos para definir una política de almacenamiento en caché.

Aquí tienes un ejemplo de archivo de modelo:

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

Crear archivos de panel de control de LookML

Para incluirse en Looker Marketplace, cada bloque debe incluir un mínimo de tres paneles de LookML que proporcionen análisis útiles y significativos. Los paneles de control deben ser estéticos, funcionales y completos, y no deben incluir datos borrosos.

Aunque no hay requisitos de diseño estrictos para los paneles de control de LookML, Looker recomienda seguir estas prácticas recomendadas de diseño generales:

  • Paleta de colores coherente en todo el panel de control
  • Al menos siete recuadros
  • Un mínimo de tres tipos de visualización diferentes (por ejemplo, de un solo valor, de barras y de líneas)

Las visualizaciones personalizadas no se admiten al desarrollar paneles de control para bloques. En su lugar, usa los tipos de visualización nativos de Looker.

Consulta las páginas de documentación sobre los parámetros de los paneles de control y los parámetros de los elementos de los paneles de control para obtener más información sobre cómo personalizar los paneles de control de LookML y las visualizaciones que contienen, respectivamente. Consulte el archivo del panel de control de LookML de administrador de Redshift del bloque de administrador de Redshift para ver un ejemplo de archivo de panel de control de LookML.

Crear un archivo marketplace.json

Crea un archivo marketplace.json para proporcionar información sobre cómo debe mostrarse la ficha en el mercado. Cada bloque de Looker Marketplace debe proporcionar esta información adicional para ayudar a los usuarios a seleccionar el bloque que mejor se adapte a sus necesidades. Tu archivo marketplace.json debe contener lo siguiente:

  • Campos de Marketplace label, category_label y branding
  • Una lista de constantes de LookML que los usuarios deberán rellenar para completar el modelo LookML (por ejemplo, nombres de conexión)

Aquí tienes un ejemplo de un archivo marketplace.json para el bloque Rendimiento de 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"
    }
  ]
}

En la siguiente captura de pantalla se muestra la ficha de Google Marketplace que se generaría con este archivo marketplace.json.

Una ficha de Marketplace de ejemplo.

  • El campo "label" controla el título del bloque. En este ejemplo, se trata de Rendimiento de Google BigQuery.
  • El campo "tagline" controla el primer párrafo de la ficha de Marketplace.
  • El campo "image_uri" controla la imagen que se muestra en la esquina superior izquierda de la ficha de Marketplace. En este ejemplo, se trata del logotipo de Google Cloud.
  • El campo "constants" pide a los usuarios que rellenen sus constantes en la interfaz de Marketplace durante el proceso de instalación. En este ejemplo, se enumeran tres constantes en el archivo marketplace.json (CONNECTION_NAME, SCHEMA_NAME y AUDIT_LOG_EXPORT_TABLE_NAME), por lo que se pedirá al usuario que especifique valores para esos tres campos antes de instalar.

Crear un archivo LICENSE

Todos los bloques de Looker deben tener una licencia de software libre MIT. Incluye el texto de esta licencia en un archivo llamado LICENSE. Consulta el archivo de licencia de Redshift Admin Block para ver un ejemplo de archivo de licencia.

Crear un archivo README

El archivo README debe contener todas las instrucciones para implementar el bloque y debe identificar explícitamente dónde se necesitan personalizaciones, como en el archivo de manifiesto generado automáticamente](#the_autogenerated_manifest_file) o en el archivo de refinamientos. Consulta el archivo README de Redshift Admin Block para ver un ejemplo de archivo README.

Cosas que debes tener en cuenta en tu archivo README:

  • ¿Qué fuente de datos necesita el usuario? ¿Tienen que pagar una suscripción?
  • ¿Qué permisos debe tener el usuario de la base de datos?
  • ¿Qué ajustes de conexión de Looker se necesitan?
  • ¿Los nombres de los campos de bloque coincidirán con los nombres de los campos del conjunto de datos del usuario? Si no es así, ¿qué debe cambiar el usuario?

Archivos generados automáticamente

Cuando los usuarios instalan tu bloque, su instancia de Looker crea un proyecto de Looker con los archivos de tu proyecto como archivos de solo lectura. También se generarán automáticamente los siguientes archivos para el usuario:

  • Un archivo marketplace_lock.lkml de solo lectura que contiene información sobre la ficha de mercado
  • Un archivo de manifiesto que hace referencia a la ficha de marketplace_lock.lkml
  • Un archivo refinements.lkml que incluye todas las vistas y exploraciones de tu bloque
  • Un archivo de modelo de solo lectura que incluye tanto el archivo de modelo de tu bloque como el archivo refinements.lkml

Los usuarios que instalen tu bloque desde Looker Marketplace pueden usar el archivo refinements.lkml para refinar tu LookML e incluso añadir nuevos archivos LookML. Consulta la página de documentación Personalizar bloques de Looker Marketplace para obtener más información sobre cómo pueden personalizar tu bloque los usuarios.

El archivo de manifiesto generado automáticamente

El archivo de manifiesto generado automáticamente permite a los usuarios que instalan tu bloque definir variables, como el nombre de la conexión. Las constantes de LookML definidas en el archivo de manifiesto del bloque se pueden editar en el archivo de manifiesto generado automáticamente o las pueden definir los usuarios en la interfaz de usuario de descarga del bloque.

El archivo de acotaciones

El archivo refinements.lkml generado automáticamente permite a los usuarios que instalan tu bloque refinar las vistas y los Exploraciones que se definen en tu bloque. Aquí es donde los usuarios que descarguen tu bloque harán la mayor parte de la personalización de LookML para adaptarlo a su caso práctico.

A continuación, se muestra un ejemplo de archivo refinements.lkml generado automáticamente:

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"
\#     }
\#

Hacer que el proyecto de bloques sea accesible

Aloja tu LookML de bloque en un repositorio de GitHub de acceso público.

Todos los bloques de Looker deben tener una licencia de código abierto MIT, y el texto de la licencia debe incluirse en un archivo LICENSE del repositorio.

Enviar el bloqueo a revisión

Cuando tu bloque esté listo para enviarse, sigue las instrucciones de Enviar contenido a Looker Marketplace para crear la documentación complementaria de tu bloque, enviarlo al equipo de Looker para que lo revise y publicarlo en Looker Marketplace.