Esta página descreve como criar um bloco personalizado que pode ser adicionado ao Marketplace do Looker e acessado por outros usuários do Looker.
É necessário ser membro da Looker Partner Network ou cliente do Looker para enviar conteúdo ao Marketplace do Looker.
Para informações sobre blocos do Looker que já estão criados e disponíveis para uso, consulte a página de documentação Blocos do Looker. Para mais informações sobre como personalizar blocos instalados do Marketplace, consulte a página de documentação Como personalizar blocos do Looker Marketplace.
Para desenvolver um bloco e disponibilizá-lo a todos os usuários do Looker no Marketplace do Looker, siga as etapas descritas nesta página:
- Configure e conecte a fonte de dados ao Looker.
- Crie um projeto e adicione os arquivos necessários.
- Torne seu bloco acessível.
- Envie seu bloqueio para análise do Looker.
Como configurar e conectar a fonte de dados ao Looker
Os blocos são modelos de dados, por isso funcionam melhor quando são projetados para um conjunto de dados específico e facilmente repetível. A maioria dos erros de instalação em bloco ocorre quando o conjunto de dados do usuário não corresponde aos nomes de esquema, tabela e campo no bloco.
- Se você estiver criando um bloco para um conjunto de dados específico, como dados do Google Analytics, anote todas as configurações ou personalizações que fez nele. Sempre que possível, faça o mínimo de personalizações possível para facilitar a instalação para os usuários. Forneça instruções específicas em um arquivo README.
- Se você estiver criando um bloco para um padrão analítico geral, como retenção de coorte, anote quais campos espera que o conjunto de dados do usuário contenha. Provavelmente, seus usuários não terão os mesmos nomes de esquema, tabela e campo que seu conjunto de dados. Use constantes do LookerML para nomes de tabelas e campos e informe ao usuário quais campos precisam ser atualizados em um arquivo README.
Depois de determinar sua fonte de dados, conecte-a ao Looker para começar a modelar. Se você precisar alterar alguma das configurações de conexão padrão, anote no arquivo README.
Como criar um projeto e adicionar os arquivos necessários
Crie um projeto para representar seu bloco. Considere usar uma convenção de nomenclatura como block-<database_dialect>-<role> (por exemplo, block-redshift-admin).
Depois, crie os seguintes arquivos no seu projeto:
- Um arquivo de manifesto que define o nome do projeto, da conexão e quaisquer outras constantes
- Um arquivo para cada visualização
- Um arquivo de exploração para cada Explore
- Arquivo de modelo que inclui todos os arquivos de visualização, de exploração e de dashboard do LookML no projeto
- Pelo menos três arquivos LookML dashboard
- Um arquivo
marketplace.jsonque contém informações que serão exibidas na listagem do Marketplace para este bloco - Um arquivo LICENÇA que inclua o texto da licença de código aberto MIT
- Um arquivo README que detalha as instruções e opções de configuração
Os usuários que instalam o bloco podem refinar as Análises, visualizações e painéis básicos em um arquivo refinements.lkml separado. As seções a seguir explicam cada tipo de arquivo necessário em mais detalhes:
- Como criar um arquivo de manifesto
- Como criar arquivos de visualização e análise
- Como criar um arquivo modelo
- Como criar arquivos do dashboard do LookML
- Como criar um arquivo marketplace.json
- Como criar um arquivo LICENÇA
- Como criar um arquivo README
Como criar um arquivo de manifesto
Crie um arquivo de manifesto para seu projeto. O arquivo de manifesto precisa começar com um nome de projeto e definir algumas constantes do LookerML para os usuários mudarem. Por exemplo, defina o nome da conexão do Looker como uma constante com export: override_required para que os usuários possam substituí-lo pelo próprio nome de conexão.
Veja um exemplo de arquivo de manifesto:
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
}
Como criar arquivos de visualização e exploração
Crie um arquivo view.lkml para cada visualização. Se os nomes de esquema e tabela de um usuário forem diferentes dos seus, defina esses nomes como constants no seu arquivo de manifesto para que os usuários que fizerem o download do seu bloco atualizem os nomes do esquema e da tabela no arquivo de manifesto gerado automaticamente. Em seguida, faça referência a essas constantes nos parâmetros sql_table_name das suas visualizações.
Confira um exemplo de um arquivo view.lkml em bloco:
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}
}
}
Em seguida, crie um ou mais arquivos explore.lkml. Confira se cada arquivo do Explore inclui as visualizações necessárias. Crie suas Análises detalhadas com cuidado para incluir mesclagens lógicas, detalhamentos e páginas selecionadas. Depois que outro usuário instalar o bloco do Marketplace, os usuários comerciais podem acessar e analisar os dados com facilidade.
Você encontra uma lista geral de práticas recomendadas de modelagem no Fórum da comunidade e nas Práticas recomendadas do Looker, como Práticas recomendadas: o que fazer e o que não fazer no LookML e Prática recomendada: como escrever um LookML sustentável e sustentável.
Veja um exemplo de um arquivo 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
}
}
Como criar um arquivo modelo
Crie um arquivo modelo que inclua todos os arquivos de visualização, análise e painel no seu projeto. Confira se o nome da conexão é referenciado como uma constante LookML no arquivo de manifesto.
Defina pelo menos um datagroup para configurar uma política de armazenamento em cache.
Aqui está um exemplo de um arquivo 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;;
}
Como criar arquivos do dashboard do LookML
Para inclusão no Marketplace do Looker, cada bloco precisa incluir pelo menos três painéis do LookerML que ofereçam uma análise significativa e útil. Os painéis devem ser estéticos, funcionais e abrangentes e não devem apresentar dados desfocados.
Embora não haja requisitos de design rígidos para dashboards do LookML, o Looker recomenda estas práticas gerais de design:
- Paleta de cores consistente em todo o painel
- Pelo menos sete blocos
- No mínimo três tipos de visualização (por exemplo, valor único, barra e linha)
As visualizações personalizadas não são compatíveis com o desenvolvimento de painéis para o Blocks. Use os tipos de visualização nativa do Looker.
Consulte as páginas de documentação Parâmetros do painel e Parâmetros do elemento do dashboard para mais informações sobre como personalizar os dashboards do LookML e as visualizações nos dashboards do LookML. Consulte o arquivo de painel do LookML do administrador do Redshift no bloco de administradores do Redshift para ver um exemplo de um arquivo do dashboard do LookML.
Como criar um arquivo marketplace.json
Crie um arquivo marketplace.json para fornecer informações sobre como a ficha da empresa deve ser exibida no Marketplace. Cada bloco no Marketplace do Looker precisa oferecer essas informações adicionais para ajudar os usuários a selecionar o bloco que melhor atende às necessidades deles. Seu arquivo marketplace.json precisa conter:
- Campos
label,category_labelebrandingdo Marketplace - Uma lista de constants do LookML que precisam ser preenchidas pelos usuários para preencher o modelo LookML (por exemplo, nomes de conexão)
Veja um exemplo de arquivo marketplace.json para o bloco de desempenho do 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"
}
]
}
A captura de tela a seguir mostra a listagem do Marketplace que seria gerada por este arquivo marketplace.json.
- O campo
"label"controla o título do bloco. Neste exemplo, o nome é Desempenho do Google BigQuery. - O campo
"tagline"controla o primeiro parágrafo da página de detalhes do Marketplace. - O campo
"image_uri"controla a imagem mostrada no canto superior esquerdo da página de detalhes do Marketplace. Neste exemplo, este é o logotipo do Google Cloud. - O campo
"constants"solicita que os usuários preencham as constantes na interface do Marketplace durante o processo de instalação. Nesse exemplo, três constantes são listadas no arquivomarketplace.json(CONNECTION_NAME,SCHEMA_NAMEeAUDIT_LOG_EXPORT_TABLE_NAME). Portanto, o usuário será solicitado a especificar valores para esses três campos antes da instalação.
Como criar um arquivo LICENÇA
Todos os blocos do Looker precisam ser licenciados sob a licença de código aberto do MIT (em inglês). Inclua o texto desta licença em um arquivo chamado LI. Consulte o arquivo LICENÇA de bloqueio de administrador do Redis para ver um exemplo de arquivo LICENÇA.
Como criar um arquivo README
O arquivo README precisa conter todas as instruções para implementar o bloco e identificar explicitamente onde alguma personalização é necessária, como no arquivo de manifesto gerado automaticamente](#the_autogenerated_manifest_file) ou no arquivo de refinamentos. Consulte o arquivo README de bloco de administrador do Redis para ver um exemplo de arquivo README.
Considerações sobre o README:
- De qual origem de dados o usuário precisa? É preciso pagar por uma assinatura?
- Quais permissões o usuário do banco de dados deve ter?
- Quais configurações de conexão do Looker são necessárias?
- Os nomes dos campos do bloco corresponderão aos nomes dos campos no conjunto de dados do usuário? Se não, o que o usuário deve mudar?
Arquivos gerados automaticamente
Quando os usuários instalam seu bloco, a instância do Looker cria um novo projeto do Looker com os arquivos do seu projeto como arquivos somente leitura. Os seguintes arquivos também serão gerados automaticamente para seu usuário:
- Um arquivo
marketplace_lock.lkmlsomente leitura que contém informações sobre as informações do produto no Marketplace - Um arquivo de manifesto que faz referência à listagem de
marketplace_lock.lkml - Um arquivo
refinements.lkmlque inclui todas as visualizações e explorações do seu bloco. - Um arquivo de modelo somente leitura que inclui o arquivo de modelo do bloco e o arquivo
refinements.lkml
Os usuários que instalarem o bloco no Marketplace do Looker poderão usar o arquivo refinements.lkml para refinar o LookML e adicionar novos arquivos do LookML. Consulte a página de documentação Como personalizar blocos do Looker Marketplace para saber como os usuários podem personalizar seu bloco.
O arquivo de manifesto gerado automaticamente
O arquivo de manifesto gerado automaticamente permite que os usuários que instalam seu bloco definam variáveis, como o nome da conexão. As constantes do LookML definidas no arquivo de manifesto de bloqueio podem ser editadas no arquivo de manifesto gerado automaticamente ou definidas pelos usuários na interface do usuário de download em blocos.
O arquivo de refinamentos
O arquivo refinements.lkml gerado automaticamente permite que os usuários que instalam seu bloco refinem visualizações e Análises definidas no bloco. É nesse local que os usuários que fizerem o download do bloco vão fazer a maior parte da personalização do LookML de acordo com o caso de uso.
Veja um exemplo de um arquivo refinements.lkml gerado automaticamente:
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"
\# }
\#
Como tornar o projeto em bloco acessível
Hospede o LookML de bloco em um repositório do GitHub de acesso público (link em inglês).
Todos os blocos do Looker precisam ser licenciados sob a licença de código aberto do MIT (em inglês), e o texto da licença precisa ser incluído em um arquivo de LICENÇA no repositório.
Como enviar o bloqueio para análise
Quando o bloco estiver pronto para envio, siga as instruções em Como enviar conteúdo ao Marketplace do Looker para criar a documentação de suporte, enviar o bloqueio à equipe do Looker para análise e publicar no Marketplace do Looker.