Nesta página, descrevemos como criar um bloco personalizado que pode ser adicionado ao Marketplace do Looker e acessado por outros usuários do Looker.
Você precisa ser membro da rede de parceiros do Looker 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 os blocos que você instalou no 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 pelo Marketplace, siga as etapas descritas nesta página:
- Configure e conecte a origem de dados ao Looker.
- Crie um projeto e adicione 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
Blocos são modelos de dados, por isso eles funcionam melhor quando 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 os dados do Google Analytics, anote todas as configurações ou personalizações feitas no conjunto de dados. Sempre que possível, reduza o mínimo possível essas personalizações 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. É provável que os usuários não tenham os mesmos nomes de esquema, tabela e campo do 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 sua fonte de dados, conecte-a ao Looker para começar a modelar. Se você precisar mudar alguma das configurações de conexão padrão, faça uma anotação 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).
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 exploração 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
- Um arquivo README que detalha as 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 substituí-lo 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 de acesso ao conteúdo
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-os como constantes no arquivo de manifesto para que os usuários que fizerem o download do bloco possam atualizar os nomes de esquema e 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 exploração inclui as visualizações necessárias para essa análise. Crie suas Análises com cuidado para incluir junções lógicas, exercícios e páginas 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ê encontra uma lista geral de práticas recomendadas para 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: criar um LookML sustentável e sustentável.
Confira um exemplo de 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, exploração e painel no seu projeto. Confira se o nome da conexão está referenciado como uma constante LookML do seu 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 os 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 diferentes 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 de elementos do painel para mais informações sobre como personalizar os painéis do LookML e as visualizações neles, respectivamente. Consulte o arquivo de painel do LookML do administrador do Redshift no bloco de administração do Redshift para ver um exemplo de arquivo de painel do LookML.
Como criar um arquivo marketplace.json
Crie um arquivo marketplace.json para fornecer informações sobre como a ficha 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. O arquivo marketplace.json deve conter:
- Campos
label,category_labelebrandingdo Marketplace - Uma lista de constantes do LookML que precisam ser preenchidas pelos usuários para preencher o LookML do modelo (por exemplo, nomes de conexões)
Confira 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 esse arquivo marketplace.json.
- O campo
"label"controla o título do bloco. Neste exemplo, é o Google BigQuery Performance. - O campo
"tagline"controla o primeiro parágrafo da listagem do Marketplace. - O campo
"image_uri"controla a imagem mostrada no canto superior esquerdo da página de detalhes do produto no 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.
Como criar 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 qual 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 do seu bloco - Um arquivo modelo somente leitura que inclui o arquivo modelo do seu bloco e o arquivo
refinements.lkml
Os usuários que instalam seu bloco no Marketplace do Looker podem usar o arquivo refinements.lkml para refinar seu 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 definidas pelos usuários na interface do usuário de download de blocos.
O arquivo de refinamentos
O arquivo refinements.lkml gerado automaticamente permite que os usuários que instalam seu bloco refinam as visualizações e as páginas "Explorar" que são definidas no bloco. É aqui que os usuários que fazem o download do seu bloco farão 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 seu bloco LookML em um repositório do GitHub acessível publicamente.
Todos os blocos do Looker precisam ser licenciados sob a licença de código aberto MIT, e o texto da licença precisa ser incluído em um arquivo LICENSE no repositório.
Como enviar o bloco 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.