En esta página, se describe cómo crear un bloque personalizado que se puede agregar a Looker Marketplace y al que otros usuarios de Looker pueden 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. Si quieres obtener información para personalizar los bloques que instalaste desde Marketplace, consulta la página de documentación Personaliza los bloques de Looker Marketplace.
Para desarrollar un bloque 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:
- Configura y conecta la fuente de datos a Looker.
- Crea un proyecto y agrega los archivos necesarios.
- Haz que tu bloque sea accesible.
- Envía el bloqueo para que se revise en 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 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 estás creando un componente para un conjunto de datos específico, como los datos de Google Analytics, toma nota de los parámetros de configuración o las personalizaciones que hayas hecho al conjunto de datos. Cuando sea posible, mantén esas personalizaciones al mínimo para optimizar la instalación para tus usuarios. Proporciona instrucciones específicas en un archivo README.
- Si estás creando un componente para un patrón analítico general, como la retención de cohorte, toma nota de qué campos 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 constantes de LookerML 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, conecta tu fuente de datos a Looker para poder comenzar a modelar. Si necesitas cambiar alguna de las opciones de configuración predeterminada de la conexión, toma nota en el 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 para cada vista
- Un archivo de exploración para cada exploración
- Un archivo de modelo que incluye todos los archivos de vista, los archivos de exploración y los archivos de panel de LookML en el proyecto
- Al menos tres archivos del panel de Looker
- Un archivo
marketplace.jsoncon información que se mostrará en la ficha de Marketplace para este bloque - Un archivo LICENSE que incluye el texto de la licencia de código abierto MIT
- Un archivo README que detalla las instrucciones y opciones de configuración
Los usuarios que instalen tu bloque podrán definir mejor las exploraciones, las vistas y los paneles base en un archivo refinements.lkml independiente. En las siguientes secciones, se explica con más detalle cada tipo de archivo requerido:
- Cómo crear un archivo de manifiesto
- Cómo crear archivos de vistas y exploración
- Crea un archivo de modelo
- Crea archivos de panel de LookML
- Crea un archivo marketplace.json
- Cómo crear un archivo LICENSE
- Crea un archivo README
Cómo crear un archivo de manifiesto
Crea un archivo de manifiesto para tu proyecto. El archivo de manifiesto debe comenzar con el nombre de un proyecto y, luego, definir algunas constantes de LookerML 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 anularla con su propio nombre de conexión.
Este es un archivo de manifiesto de muestra:
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 del esquema y la tabla como constants 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. Luego, haz referencia a esas constantes en los parámetros sql_table_name de tus vistas.
Este es un ejemplo de un 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 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, simulacros y páginas seleccionadas de Explorar. Después de que otro usuario instale el bloque desde Marketplace, debería ser sencillo para los usuarios empresariales ingresar y comenzar a analizar sus datos.
Puedes encontrar una lista general de las prácticas recomendadas para el modelado en nuestro Foro de la comunidad y en las Prácticas recomendadas de Looker, como Práctica recomendada: Sugerencias y precauciones de LookML y Práctica recomendada: Escribe LookML sustentable y sostenible.
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 la vista, la exploración y el 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 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 de panel de LookML
Para la inclusión en Looker Marketplace, cada bloque debe incluir un mínimo de tres paneles de Looker ML que proporcionen un análisis significativo y útil. Los paneles deben ser estéticos, funcionales y completos, y no deben incluir datos desenfocados.
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 mosaicos
- 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 Blocks. En su lugar, usa los tipos de visualización nativa de Looker.
Consulta las páginas de documentación Parámetros del panel y Parámetros de los elementos 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 del administrador de Redshift en el bloque de administrador de Redshift para obtener 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 en 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
label,category_labelybrandingde Marketplace - Una lista de las constants de LookML que los usuarios deberán completar para propagar el modelo de LookML (por ejemplo, los nombres de las conexiones)
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.
- El campo
"label"controla el título del bloque. En este ejemplo, es el 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 archivomarketplace.json(CONNECTION_NAME,SCHEMA_NAMEyAUDIT_LOG_EXPORT_TABLE_NAME), por lo que se le pedirá al usuario que especifique valores para esos tres campos antes de la instalación.
Creación de un archivo LICENSE
Todos los bloques de Looker deben tener la licencia de código abierto MIT. Incluye el texto de esta licencia en un archivo llamado LICENSE. Consulta el archivo LICENSE del bloque 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 de forma explícita dónde se necesita cualquier personalización, como en el archivo de manifiesto generado automáticamente](#the_autogenerated_manifest_file) o en el archivo de perfeccionamientos. Consulta el archivo README del bloque de administración de Redshift para ver un ejemplo de un archivo README.
Aspectos que debes tener en cuenta para el archivo README:
- ¿Qué fuente de datos necesita el usuario? ¿Deben pagar una suscripción?
- ¿Qué permisos debe tener el usuario de la base de datos?
- ¿Qué parámetros de configuración de conexión de Looker se necesitan?
- ¿Los nombres del campo de bloque coincidirán con los nombres de los campos en el conjunto de datos de tu usuario? Si no es así, ¿qué debería cambiar tu 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 el usuario:
- Un archivo
marketplace_lock.lkmlde solo lectura 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.lkmlque incluya 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 instalan tu bloque desde Looker Marketplace pueden usar el archivo refinements.lkml para definir mejor tu LookML y hasta agregar nuevos archivos de LookML. Consulta la página de documentación Personaliza los bloqueos 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 bloques se pueden editar en el archivo de manifiesto generado automáticamente, o bien los usuarios pueden configurarlas en la interfaz de usuario de descarga de bloques.
El archivo de refinamientos
El archivo refinements.lkml generado automáticamente permite a los usuarios que instalan tu bloque definir mejor las vistas y las exploraciones que definen tu bloque. Aquí es donde los usuarios que descarguen tu bloque 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 en bloque en un repositorio de GitHub de acceso público.
Todos los bloques de Looker deben tener una licencia de código abierto del MIT, y el texto de la licencia debe incluirse en un archivo LICENSE en el repositorio.
Cómo enviar el bloqueo a revisión
Una vez que el bloque esté listo para enviarse, sigue las instrucciones que se indican en Envía contenido a Looker Marketplace a fin de crear documentación de respaldo para el bloqueo, envíalo al equipo de Looker para su revisión y publícalo en Looker Marketplace.