Cómo desarrollar un bloque personalizado para Looker Marketplace

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

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

Para obtener información sobre los bloques de Looker que ya se compilaron y están disponibles para su uso, consulta la página de documentación de Looker Blocks. Para obtener información sobre cómo personalizar los bloques que instaló desde Marketplace, consulte la página de documentación Personalice los bloques de Looker Marketplace.

A fin de desarrollar un bloqueo y hacer que esté disponible para 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 agrega los archivos necesarios.
  3. Haz que tu bloque sea accesible.
  4. Envía tu bloqueo para la revisión de Looker.

Configura y conecta 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 repetible. La mayoría de los errores de instalación de bloques ocurren cuando el conjunto de datos del usuario no coincide con los nombres de esquema, tabla y campo del bloque.

  • Si estás creando un bloque para un conjunto de datos específico, como datos de Google Analytics, toma nota de cualquier configuración o personalización que hayas realizado en el conjunto de datos. Cuando sea posible, reduzca al mínimo esas personalizaciones para optimizar la instalación de sus usuarios. Proporcionar instrucciones específicas en un archivo README
  • Si estás creando un bloque para un patrón analítico general, como la retención de cohorte, toma nota de los campos que esperas que contenga el conjunto de datos del usuario. Lo más probable es que tus usuarios no tengan los mismos nombres de esquema, tabla y campo que los de tu conjunto de datos. Usa constantes de LookML para los nombres de tablas y campos y, luego, informa al usuario qué campos debe actualizar en un archivo README.

Una vez que hayas determinado tu fuente de datos, conéctala a Looker para comenzar a modelarla. Si necesitas cambiar la configuración de la conexión predeterminada, anota en tu archivo README.

Crea un proyecto y agrega los archivos necesarios

Crea un proyecto para representar tu bloque. Considera usar una convención de nombres 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 para cada Explorar
  • Un archivo de modelo que incluye todos los archivos de vista, archivos de exploración y archivos del panel de LookML en el proyecto
  • Al menos tres archivos de panel de LookML
  • Un archivo marketplace.json que contiene información que se mostrará en la ficha de Marketplace correspondiente a este bloque
  • Un archivo de LICENCIA que incluya el texto de la licencia de código abierto del MIT
  • Un archivo README que detalla las opciones y las instrucciones de configuración

Los usuarios que instalen tu bloque podrán definir mejor las Explorars, las vistas y los paneles de base en un archivo refinements.lkml independiente. Las siguientes secciones explican cada tipo de archivo requerido en más detalle:

Cómo crear un archivo de manifiesto

Crea un archivo de manifiesto para tu proyecto. El archivo de manifiesto debe comenzar con un nombre de proyecto y, luego, definir algunas constantes de LookML para que sus usuarios cambien. Por ejemplo, debes definir el nombre de la conexión de Looker como una constante con export: override_required para que los usuarios puedan anularla con su propio nombre de conexión.

A continuación, se muestra un ejemplo de un archivo de manifiesto:

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
}

Crea archivos de vista y exploración

Crea un archivo view.lkml para cada vista. Si los nombres de esquema y tabla de un usuario pueden diferir de los tuyos, asegúrate de definir los nombres del esquema y de la tabla como constantes en tu archivo de manifiesto para que los usuarios que descarguen tu bloque puedan actualizar los nombres del esquema y la tabla en el archivo de manifiesto generado automáticamente. Luego, haz referencia a esas constantes en los parámetros sql_table_name de tus vistas.

Este es un ejemplo de un archivo view.lkml de bloque: 

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 más archivos explore.lkml. Asegúrate de que cada archivo de exploración incluya las vistas necesarias para esa exploración. Diseña tus elementos Explorar de manera minuciosa para contener uniones lógicas, ejercicios y páginas de Explorar seleccionadas. Después de que otro usuario instala el bloque de Marketplace, los usuarios empresariales deberían poder comenzar a analizar sus datos fácilmente.

Puedes encontrar una lista general de las prácticas recomendadas sobre modelado en nuestro Foro de la comunidad y en el Centro de ayuda de Looker, como Práctica recomendada: LookML Dos y Dons y Práctica recomendada: Cómo escribir Sustentable, Mantener aspecto LookML.

Este es un ejemplo de un 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
  }
}

Crea un archivo de modelo

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

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

Este es un ejemplo de un 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;;
}

Crea archivos del panel de LookML

Para que se incluya en el Marketplace de Looker, cada bloque debe incluir un mínimo de tres paneles de LookML que proporcionen un análisis significativo y útil. Los paneles deben ser estéticos, funcionales y completos, y no deben incluir datos difuminados.

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

  • Paleta de colores coherente en todo el panel
  • Al menos siete mosaicos
  • Un mínimo de tres tipos de visualización diferentes (por ejemplo, valor único, barra y línea)

No se admiten las visualizaciones personalizadas al desarrollar paneles para Blocks. En su lugar, usa los tipos de visualización nativa de Looker.

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

Crea un archivo marketplace.json

Crea un archivo marketplace.json para proporcionar información sobre cómo se debe mostrar la ficha en Marketplace. Cada bloque del mercado de Looker 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 label, category_label y branding de Marketplace
  • Una lista de constantes de LookML que los usuarios deberán completar para propagar el modelo LookML (por ejemplo, nombres de conexión)

A continuación, se muestra un ejemplo de un archivo marketplace.json para el bloque de 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 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"
    }
  ]
}

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

  • El campo "label" controla el título del bloque. En este ejemplo, es 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, este es el logotipo de Google Cloud.
  • El campo "constants" solicita a los usuarios que propaguen sus constantes en la IU 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 le pedirá al usuario que especifique valores para esos tres campos antes de la instalación.

Creando un archivo de LICENSE

Todos los bloques de Looker deben tener una licencia de código abierto MIT. Incluya el texto de esta licencia en un archivo llamado LICENSE. Consulta el archivo LICENSE de bloqueo del administrador de Redshift para ver un ejemplo de un archivo LICENSE.

Crea un archivo README

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

Aspectos que debes tener en cuenta para tu archivo README:

  • ¿Qué fuente de datos necesita el usuario? ¿Es necesario que paguen una suscripción?
  • ¿Qué permisos debería tener el usuario de la base de datos?
  • ¿Qué configuración de conexión de Looker se necesita?
  • ¿Los nombres de los campos de bloque coincidirán con los nombres de campo del conjunto de datos de tu usuario? De lo contrario, ¿qué debería cambiar el usuario?

Archivos generados automáticamente

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

  • Un archivo de solo lectura marketplace_lock.lkml que contiene información de la ficha de Marketplace
  • 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 el archivo del modelo de tu bloque y el archivo refinements.lkml

Los usuarios que instalen tu bloque de Looker Marketplace pueden usar el archivo refinements.lkml para definir mejor tu LookML y, además, pueden agregar archivos nuevos. Consulta la página de documentación Personaliza bloques de Marketplace de Looker para obtener más información sobre cómo los usuarios pueden personalizar tu bloqueo.

El archivo de manifiesto generado automáticamente

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

El archivo de mejoras

El archivo refinements.lkml generado automáticamente permite que los usuarios que instalan tu bloque perfeccionan las vistas y las exploraciones definidas para tu bloque. Aquí es donde los usuarios que descargan tu bloqueo realizarán la mayor parte de la personalización de LookML para que se ajuste a su caso de uso.

Este es un ejemplo de un 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"
\#     }
\#

Cómo hacer que el proyecto de bloque sea accesible

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

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

Cómo enviar el bloqueo para su revisión

Una vez que el bloqueo esté listo para su envío, sigue las instrucciones en Cómo enviar contenido a Looker Marketplace a fin de crear documentación de respaldo para el bloqueo, enviarlo al equipo de Looker para su revisión y publicarlo en Looker Marketplace.