Esta página descreve como criar um bloco personalizado que pode ser adicionado ao Looker Marketplace e acessado por outros usuários do Looker.
Você precisa ser membro da rede de parceiros ou cliente do Looker para enviar conteúdo ao Marketplace do Looker.
Para informações sobre os blocos do Looker que já foram criados e estão disponíveis para uso, consulte a página de documentação Blocos do Looker. Para saber como personalizar blocos que você instalou do Marketplace, consulte a página de documentação Personalizar blocos do Marketplace do Looker.
Para desenvolver um bloco e disponibilizá-lo a todos os usuários do Looker pelo Marketplace, siga as etapas descritas nesta página:
- Configure e conecte a origem de dados ao Looker.
- Criar um projeto e adicionar os arquivos necessários
- Torne seu bloco acessível.
- Envie seu bloco para análise do Looker.
Configurar e conectar a fonte de dados ao Looker
Os blocos são modelos de dados, então funcionam melhor quando projetados para um conjunto de dados específico e facilmente repetível. A maioria dos erros de instalação de 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 feitas no conjunto. Quando possível, mantenha essas personalizações no mínimo para agilizar 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 em seu conjunto de dados. Use as constantes do LookML para nomes de tabelas e campos e informe ao usuário quais campos precisam ser atualizados em um arquivo README.
Depois de determinar a fonte de dados, conecte-a ao Looker para começar a modelagem. Se você precisar alterar qualquer uma das configurações de conexão padrão, anote o arquivo README.
Como criar um projeto e adicionar os arquivos necessários
Crie um projeto para representar seu bloco. Use uma convenção de nomenclatura como block-<database_dialect>-<role> (por exemplo, block-redshift-admin).
Em seguida, crie os seguintes arquivos no projeto:
- Um arquivo de manifesto que define o nome do projeto, o nome da conexão e outras constantes.
- Um arquivo de visualização para cada visualização
- Um arquivo de análise para cada análise
- Arquivo de modelo que inclui todos os arquivos de visualização, arquivos de exploração e arquivos do dashboard do LookML no projeto.
- Pelo menos três arquivos do painel do LookML
- Um arquivo
marketplace.jsonque contém informações que serão exibidas na listagem do Marketplace para esse bloco - Um arquivo LICENSE que inclui o texto da licença de código aberto MIT
- Arquivo README que detalha instruções e opções de configuração
Os usuários que instalarem seu bloco poderão refinar a base das Análises, visualizações e painéis 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 exploração
- Como criar um arquivo de modelo
- Como criar arquivos de dashboard do LookML
- Como criar um arquivo marketplace.json
- Como criar um arquivo LICENSE
- Como criar um arquivo README
Como criar um arquivo de manifesto
Crie um arquivo de manifesto para o projeto. O arquivo de manifesto precisa começar com o nome do projeto e definir algumas constantes do LookML para que os usuários possam mudar. Por exemplo, defina o nome da conexão do Looker como uma constante com export: override_required para que os usuários possam o substituir pelo próprio nome de conexão.
Confira 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 análise
Crie um arquivo view.lkml para cada visualização. Se os nomes do esquema e da tabela de um usuário forem diferentes dos seus, defina os nomes do esquema e das tabelas como constantes no arquivo de manifesto para que os usuários que fizerem o download do bloco possam atualizar o esquema e os nomes 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 arquivo view.lkml de 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. Verifique se cada arquivo de análise inclui as visualizações necessárias para ela. Projete suas análises detalhadas para incluir mesclagens lógicas, análises detalhadas e páginas de análise detalhadas selecionadas. Depois que outro usuário instala o bloco do Marketplace, os usuários comerciais podem começar a analisar os dados com facilidade.
Você pode encontrar uma lista geral de práticas recomendadas de modelagem no nosso fórum da comunidade e nas práticas recomendadas do Looker, como Prática recomendada: o que fazer e o que não fazer com o LookML e Prática recomendada: como escrever um LookML sustentável e de fácil manutenção.
Aqui está 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 de modelo
Crie um arquivo de modelo que inclua todos os arquivos de visualização, análise detalhada e painel do seu projeto. Confira se o nome da conexão é referenciado como uma constante do LookML no arquivo de manifesto.
Defina pelo menos um datagroup para definir uma política de cache.
Confira um exemplo de 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 de dashboard do LookML
Para inclusão no Marketplace do Looker, cada bloco precisa incluir pelo menos três painéis do LookML que forneçam análises relevantes e úteis. Os painéis precisam ser estéticos, funcionais e abrangentes, e não podem ter dados desfocados.
Embora não haja requisitos de design rígidos para painéis do LookML, o Looker recomenda estas práticas recomendadas gerais de design:
- Paleta de cores consistente em todo o painel
- Pelo menos sete blocos
- No mínimo três tipos de visualização diferentes (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 dashboard e Parâmetros de elementos do dashboard para mais informações sobre como personalizar os dashboards do LookML e as visualizações nos dashboards do LookML, respectivamente. Consulte o arquivo de dashboard do LookML do administrador do Redshift no bloco de administrador do Redshift para conferir um exemplo de arquivo de dashboard do LookML.
Como criar um arquivo marketplace.json
Crie um arquivo marketplace.json para fornecer informações sobre como a listagem será exibida no Marketplace. Cada bloco no Marketplace do Looker precisa fornecer essas informações adicionais para ajudar os usuários a selecionar o bloco que melhor se adapta às necessidades deles. Seu arquivo marketplace.json precisa conter:
- Campos
label,category_labelebrandingdo Marketplace - Uma lista de constantes do LookML que precisarão ser preenchidas pelos usuários para preencher o LookML do modelo (por exemplo, nomes de conexões).
Veja um exemplo de um arquivo marketplace.json para o bloco "Performance" 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 esse arquivo marketplace.json.
- O campo
"label"controla o título do bloco. Neste exemplo, é Google BigQuery Performance. - O campo
"tagline"controla o primeiro parágrafo da página de detalhes do produto no Marketplace. - O campo
"image_uri"controla a imagem mostrada no canto superior esquerdo da listagem do Marketplace. Neste exemplo, é 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. Neste exemplo, três constantes são listadas no arquivomarketplace.json(CONNECTION_NAME,SCHEMA_NAMEeAUDIT_LOG_EXPORT_TABLE_NAME). Portanto, o usuário vai precisar especificar valores para esses três campos antes da instalação.
Criando um arquivo LICENSE
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 LICENSE. Consulte o arquivo LICENSE do bloco de administrador do Redshift para conferir um exemplo de um arquivo LICENSE.
Como criar um arquivo README
O arquivo README precisa conter todas as instruções para implementar o bloco e identificar explicitamente onde as personalizações são necessárias, como no arquivo de manifesto gerado automaticamente (link em inglês) ou no arquivo de refinamentos. Consulte o arquivo README de bloco Admin do Redshift para ver um exemplo.
Considerações para o README:
- De que fonte de dados o usuário precisa? Eles precisam pagar por uma assinatura?
- Quais permissões o usuário do banco de dados precisa ter?
- Quais configurações de conexão do Looker são necessárias?
- Os nomes dos campos do bloco vão corresponder aos nomes dos campos no conjunto de dados do usuário? Caso contrário, o que o usuário precisa mudar?
Arquivos gerados automaticamente
Quando os usuários instalam seu bloco, a instância do Looker cria um novo projeto com os arquivos do seu projeto como arquivos somente leitura. Ele também gera automaticamente os seguintes arquivos para seu usuário:
- Um arquivo
marketplace_lock.lkmlsomente leitura que contém informações das informações do produto do Marketplace. - Um arquivo de manifesto que faz referência à listagem de
marketplace_lock.lkml - Um arquivo
refinements.lkmlque inclui todas as visualizações e Análises detalhadas do seu bloco. - Um arquivo de modelo somente leitura que inclui o arquivo de modelo do seu bloco e o arquivo
refinements.lkml.
Os usuários que instalarem o bloco no Looker Marketplace poderão usar o arquivo refinements.lkml para refinar o LookML e até mesmo adicionar novos arquivos do LookML. Consulte a página de documentação Como personalizar blocos do Looker Marketplace para mais informações sobre 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 bloco podem ser editadas no arquivo de manifesto gerado automaticamente ou pelos usuários na interface de download em blocos.
O arquivo de refinamentos
O arquivo refinements.lkml gerado automaticamente permite que os usuários que instalarem seu bloco refinem visualizações e Análises definidas para seu bloco. É aqui que os usuários que fazem o download do bloco vão fazer a maior parte da personalização do LookML para se adequar ao caso de uso.
Confira um exemplo de 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"
\# }
\#
Tornar o projeto de bloco acessível
Hospede o LookML de blocos em um repositório do GitHub de acesso público.
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 Enviar conteúdo para o Marketplace do Looker para criar a documentação de apoio, enviar o bloco para a equipe do Looker analisar e publicar no Marketplace do Looker.