Desarrolla un bloque personalizado para Looker Marketplace

En esta página, se describe cómo crear un bloque personalizado que se pueda agregar al Mercado de Looker y al que otros usuarios de Looker puedan acceder.

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 están compilados y disponibles para su uso, consulta la página de documentación de Bloques de Looker. Para obtener información sobre cómo personalizar los bloques que instalaste desde el mercado, consulta la página de documentación Cómo personalizar bloques de Looker Marketplace.

Si quieres 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 agrega los archivos necesarios.
  3. Haz que tu bloque sea accesible.
  4. Envía tu bloque para que Looker lo revise.

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 fácil de repetir. La mayoría de los errores de instalación de bloques se producen cuando el conjunto de datos del usuario no coincide con el esquema, la tabla y los nombres de los campos del bloque.

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

Cuando hayas determinado tu fuente de datos, conéctala a Looker para comenzar a modelar. Si necesitas cambiar alguno de los parámetros de configuración de conexión predeterminados, toma nota 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 exploración
  • Un archivo de modelo que incluye todos los archivos de vista, archivos de exploración y archivos de panel de LookML en el proyecto
  • Al menos tres archivos del panel de LookML
  • Un archivo marketplace.json que contiene información que se mostrará en la ficha del mercado de este bloque
  • Un archivo LICENSE que incluya el texto de la licencia de código abierto del MIT
  • Un archivo README que detalla las instrucciones y opciones de configuración

Los usuarios que instalan tu bloque pueden definir mejor las exploraciones, las vistas y los paneles base en un archivo refinements.lkml independiente. En las siguientes secciones, se explica 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 los usuarios las 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 anularlo con su propio nombre de conexión.

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

Cómo crear archivos de vista y exploración

Crea un archivo view.lkml para cada vista. Si el esquema y los nombres de las tablas de un usuario pueden diferir de los tuyos, asegúrate de definir los nombres de esquema y tabla como constantes en tu archivo de manifiesto para que los usuarios que descarguen tu bloque puedan actualizar los nombres de esquema y 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 exploraciones cuidadosamente para que contengan uniones lógicas, ejercicios y páginas de exploración seleccionadas. Después de que otro usuario instale el bloque desde el mercado, los usuarios empresariales deberían poder comenzar a analizar sus datos con facilidad.

Puedes encontrar una lista general de prácticas recomendadas de modelado 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: Cómo escribir LookML sostenible y mantenible.

A continuación, se muestra 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 en tu archivo de manifiesto.

Define al menos un datagroup para configurar una política de almacenamiento en caché.

Aquí hay 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;;
}

Crear archivos de panel de LookML

Para que se los incluya en Looker Marketplace, cada bloque debe incluir un mínimo de tres paneles de LookML que proporcionen un análisis útil y significativo. Los paneles deben ser estéticos, funcionales y exhaustivos, 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 de diseño:

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

Las visualizaciones personalizadas no son compatibles cuando se desarrollan paneles para bloques. En su lugar, usa los tipos de visualizaciones nativas de Looker.

Consulta las páginas de documentación Parámetros de paneles y Parámetros de elementos de paneles para obtener más información sobre cómo personalizar los paneles de LookML y las visualizaciones dentro de ellos, respectivamente. Consulta el archivo del panel de LookML del administrador de Redshift del bloque de administrador de Redshift para ver un ejemplo de un archivo de 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 de Looker Marketplace debe proporcionar esta información adicional para ayudar a los usuarios a seleccionar el 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 de LookML (por ejemplo, nombres de conexión)

Este es 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 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 Marketplace que generaría este archivo marketplace.json.

Ejemplo de ficha de Marketplace

  • 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" les 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.

Crear un archivo LICENSE

Todos los bloques de Looker deben tener licencia de la licencia de código abierto de MIT. Incluye 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 bloque 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 en el archivo de perfeccionamiento. Consulta el archivo README del bloque del 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? ¿Tienen que pagar una suscripción?
  • ¿Qué permisos debería tener el usuario de la base de datos?
  • ¿Qué parámetros de configuración de conexión de Looker se necesitan?
  • ¿Los nombres de los campos del bloque coincidirán con los nombres de los campos del conjunto de datos de tu usuario? Si no es así, ¿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 del proyecto como archivos de solo lectura. También se generarán automáticamente los siguientes archivos para tu usuario:

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

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

El archivo de manifiesto generado automáticamente

El archivo de manifiesto generado automáticamente permite que los usuarios que instalan tu bloque establezcan variables, como el nombre de la conexión. Las constantes de LookML definidas en el archivo de manifiesto de bloque se pueden editar en el archivo de manifiesto generado automáticamente o pueden ser configuradas por los usuarios 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 definan mejor las vistas y las 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 que se adapte 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 bloques sea accesible

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

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

Envía el bloqueo para su revisión

Una vez que tu bloque esté listo para enviarse, sigue las instrucciones que se indican en Cómo enviar contenido a Looker Marketplace para crear documentación de respaldo para tu bloque, enviarlo al equipo de Looker para su revisión y publicarlo en Looker Marketplace.