Como desenvolver um bloco personalizado para o Looker Marketplace

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.

É necessário ser membro da rede de parceiros do Looker ou um cliente do Looker para enviar conteúdo ao Marketplace do Looker.

Para mais informações sobre os blocos do Looker que já estão criados e disponíveis para uso, consulte a página de documentação Bloqueios do Looker. Para ver informações sobre como personalizar os 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 Looker Marketplace, siga as etapas descritas nesta página:

  1. Configure e conecte a fonte de dados ao Looker.
  2. Criar um projeto e adicionar os arquivos necessários.
  3. Torne seu bloco acessível.
  4. Envie seu bloqueio para revisão do Looker.

Configurar e conectar a fonte de dados ao Looker

Os blocos são modelos de dados, portanto funcionam melhor quando são projetados para um conjunto de dados específico e de fácil repetição. A maioria dos erros de instalação em bloco ocorre quando o conjunto de dados do usuário não corresponde ao nome do esquema, da tabela e do campo no bloco.

  • Ao criar um bloco para um conjunto de dados específico, como dados do Google Analytics, anote todas as configurações ou personalizações feitas nele. Sempre que possível, mantenha essas personalizações no mínimo para simplificar a instalação para seus 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 os campos que você espera que o conjunto de dados do usuário contenha. Provavelmente, seus usuários não terão o mesmo esquema, tabela e nomes de campo do conjunto de dados. Use Constantes LookML para nomes de tabelas e campos e informe aos usuários quais campos precisam ser atualizados em um arquivo README.

Depois de determinar a 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, anote no seu 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 seu projeto:

  • Um arquivo de manifesto que define o nome do projeto, o nome da conexão e todas as outras constantes.
  • Um arquivo de visualização para cada visualização
  • Um arquivo de exploração para cada exploração
  • Um arquivo de modelo que inclui todos os arquivos de visualização, de exploração e do painel do LookML no projeto
  • Pelo menos três arquivos do painel do LookML
  • Um arquivo marketplace.json que contém as informações que serão exibidas na listagem do Marketplace para este bloco
  • Um arquivo LICENSE com 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 o bloco poderão refinar os Explorars, 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:

Criar um arquivo de manifesto

Crie um arquivo de manifesto para o projeto. O arquivo de manifesto começa com um nome de projeto e define algumas constantes do LookML 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 da 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 esquemas e tabelas de um usuário puderem ser diferentes dos seus, defina os nomes de esquemas e tabelas como constantes no arquivo de manifesto para que os usuários que fizerem o download do seu bloco possam atualizar os nomes de esquemas e tabelas 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.

Veja um exemplo de um 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. Cada arquivo precisa ter as visualizações necessárias para essa exploração. Crie cuidadosamente suas explorações para conter mesclagens, exercícios e páginas de exploração selecionadas. Depois que outro usuário instala o bloqueio do Marketplace, deve ser simples para seus usuários comerciais começarem a analisar os dados.

Veja uma lista geral de práticas recomendadas de modelagem no nosso fórum da comunidade e na Central de Ajuda do Looker, como Práticas recomendadas: LookML Dos e Don'ts e Práticas recomendadas: como criar 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 de modelo

Crie um arquivo de modelo que inclua todos os arquivos de visualização, exploração e painel no projeto. Confira se o nome da conexão é referenciado como uma ConstantML Look do arquivo de manifesto.

Defina pelo menos um datagroup para definir uma política de armazenamento em cache.

Veja 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 de painel do LookML

Para inclusão no Looker Marketplace, cada bloco precisa incluir no mínimo três painéis LookML que fornecem análises significativas e úteis. 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ígido para os 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 (por exemplo, valor único, barra e linha)

As visualizações personalizadas não são compatíveis com o desenvolvimento de painéis para blocos. Em vez disso, use os tipos de visualização nativos do Looker.

Consulte as páginas de documentação Parâmetros do painel e Parâmetros do elemento do painel para ver mais informações sobre como personalizar os painéis do LookML e as visualizações nos painéis do LookML, respectivamente. Consulte o arquivo de painel do LookML Admin do Redshift no bloco de administrador do Redshift para ver um exemplo de arquivo do painel do LookML.

Como criar um arquivo marketplace.json

Crie um arquivo marketplace.json para fornecer informações sobre como a ficha da empresa é exibida no Marketplace. Cada bloco no Looker Marketplace precisa fornecer essas informações adicionais para ajudar os usuários a selecionar o bloqueio que melhor atende às suas necessidades. Seu arquivo marketplace.json precisa conter:

  • Campos label, category_label e branding do 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ão).

Veja um exemplo de um 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 BQ 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 BQ 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 ficha do Marketplace que seria gerada por este arquivo marketplace.json.

  • O campo "label" controla o título do bloco. No exemplo, usamos o desempenho do Google BigQuery.
  • O campo "tagline" controla o primeiro parágrafo da ficha da empresa no Marketplace.
  • O campo "image_uri" controla a imagem exibida no canto superior esquerdo da listagem do Marketplace. Neste exemplo, este é o logotipo do Google Cloud.
  • O campo "constants" solicita que os usuários preencham as constantes na IU do Marketplace durante o processo de instalação. Nesse exemplo, três constantes estão listadas no arquivo marketplace.json (CONNECTION_NAME, SCHEMA_NAME e AUDIT_LOG_EXPORT_TABLE_NAME). Portanto, o usuário receberá uma solicitação para especificar valores para esses três campos antes da instalação.

Criando um arquivo LICENSE

Todos os bloqueios do Looker precisam ser licenciados sob a licença de código aberto do MIT (em inglês). Inclua o texto dessa licença em um arquivo chamado LICENSE. Consulte o arquivo LICENSE do bloco de administradores do Redshift para ver um exemplo de arquivo LICENSE.

Como criar um arquivo README

O arquivo README deve conter todas as instruções para implementar o bloco e identificar explicitamente onde quaisquer personalizações são necessárias, como no arquivo de manifesto gerado automaticamente](#the_autogenerate_manifest_file) ou no arquivo de refinamentos. Consulte o arquivo README do bloco de administração do Redshift para ver um exemplo de arquivo README.

Considerações sobre seu README:

  • De qual fonte de dados o usuário precisa? Será que precisam pagar por uma assinatura?
  • Que 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 de bloco corresponderão aos nomes dos campos do conjunto de dados do usuário? Se não forem, o que o usuário deve alterar?

Arquivos gerados automaticamente

Quando os usuários instalam seu bloco, a instância do Looker cria um novo projeto do Looker com arquivos do seu projeto como arquivos somente leitura. Ele também vai gerar automaticamente os seguintes arquivos para o usuário:

  • Um arquivo marketplace_lock.lkml somente leitura que contém informações da ficha da empresa no mercado
  • Um arquivo de manifesto que faz referência à ficha da empresa marketplace_lock.lkml
  • Um arquivo refinements.lkml que inclui todas as visualizações e explorações 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 do Looker Marketplace poderão usar o arquivo refinements.lkml para refinar o LookML e até mesmo adicionar novos arquivos 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 instalarem o bloco definam variáveis, como o nome da conexão. As constantes 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 em blocos.

O arquivo de refinamentos

O arquivo refinements.lkml gerado automaticamente permite que os usuários que instalam o bloco refinam as visualizações e as explorações que foram definidas. É 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.

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 blocos acessível

Hospede seu bloco LookML em um repositório do GitHub acessível publicamente.

Todos os bloqueios do Looker precisam ser licenciados sob a licença de código aberto do MIT, e o texto de licença precisa ser incluído em um arquivo LICENSE no repositório.

Como enviar o bloqueio para revisão

Quando o bloqueio estiver pronto para envio, siga as instruções em Como enviar conteúdo para o Looker Marketplace para criar a documentação de suporte do bloco, enviá-lo para revisão da equipe do Looker e publicá-lo no Marketplace do Looker.