En esta página, se describe cómo crear un bloque personalizado que se puede agregar al Marketplace de Looker y al que pueden acceder otros usuarios de Looker.
Ten en cuenta que debes ser miembro de la red de socios de Looker o de un 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 para usarse, consulta la página de documentación de Blocks de Looker. Para obtener información sobre cómo personalizar bloques que instaló desde Marketplace, consulte la página de documentación Cómo personalizar bloques de Looker de 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:
- 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 tu solicitud de 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 están diseñados 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á creando un bloque para un conjunto de datos específico, como datos de Google Analytics, tome nota de las opciones de configuración o las personalizaciones que realizó en el conjunto de datos. Cuando sea posible, mantenga esas personalizaciones al mínimo para optimizar la instalación para sus usuarios. Proporciona 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 sus usuarios no tengan los mismos nombres de esquema, tabla y campo que los de su conjunto de datos. Usa constantes de LookML para los nombres de tablas y campos e informa al usuario qué campos debe actualizar en un archivo README.
Una vez que haya determinado su fuente de datos, conéctela a Looker para poder comenzar a modelar. Si necesitas cambiar la configuración de la conexión predeterminada, anota el archivo README.
Cómo crear un proyecto y agregar 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).
Luego, 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 para cada exploración
- 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 del panel de LookML
- Un archivo
marketplace.jsonque contiene la información que se mostrará en la ficha de Marketplace correspondiente a este bloque - Un archivo de LICENCIA que incluye 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 instalen tu bloque podrán definir mejor las exploraciones, las vistas y los paneles básicos 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 vista y exploración
- Crea un archivo de modelo
- Crea archivos del panel de LookML
- Cómo crear un archivo marketplace.json
- Cómo crear un archivo LICENSE
- Cómo crear 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 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, de modo 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 los nombres del esquema y de la 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 exploraciones de forma minuciosa para contener uniones lógicas, ejercicios y páginas de exploración seleccionadas. Después de que otro usuario instala el bloque desde Marketplace, el usuario debería poder comenzar a analizar sus datos con facilidad.
Puedes encontrar una lista general de las prácticas recomendadas de 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: Cómo escribir un LookML sustentable y mantenible.
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"
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 del 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 poder incluirlos en Looker Marketplace, 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 mostrar datos difuminados.
Aunque no hay requisitos de diseño estrictos para los paneles de LookML, Looker recomienda estas prácticas recomendadas de diseño 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 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 de los parámetros del panel y de los parámetros 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 de Redshift del bloque de administrador de Redshift para ver un ejemplo de un archivo de panel de LookML Dashboard.
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_labelybrandingdel mercado - 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á este archivo marketplace.json.
- El campo
"label"controla el título del bloque. En este ejemplo, se llama 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 solicitará al usuario que especifique valores para esos tres campos antes de la instalación.
Cómo crear un archivo LICENSE
Todos los bloques de Looker deben tener una licencia de código abierto del MIT. Incluye el texto de esta licencia en un archivo llamado LICENSE. Consulta el archivo LICENSE del bloque de administración 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 de forma explícita en qué casos se necesitan personalizaciones, como el archivo de manifiesto generado automáticamente (##_the_autogenerate_manifest_file) o el archivo de mejoras. Consulta el archivo README de Block de administrador 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? ¿Es necesario que pague 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 del usuario? De lo contrario, ¿qué debe cambiar?
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 de solo lectura de
marketplace_lock.lkmlque 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 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 e incluso pueden agregar nuevos archivos de LookML. Consulta la página de documentación de Personalización de 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 configuren 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 a los usuarios que instalan tu bloque definir mejor las vistas y exploraciones que están definidas a tu bloque. Aquí es donde los usuarios que descarguen su bloque realizará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
Aloje su bloque de LookML 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.
Enviando el bloqueo para su revisión
Una vez que tu bloque esté listo para enviarlo, sigue las instrucciones que se indican en Cómo enviar contenido a Looker Marketplace a fin de crear documentación de respaldo para él, envía tu bloque al equipo de Looker para su revisión y publícalo en Looker Marketplace.