Como desenvolver um bloco personalizado para o Looker Marketplace

Nesta página, descrevemos 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 do Looker ou ser cliente do Looker para enviar conteúdo ao Looker Marketplace.

Para informações sobre o Looker Blocks que já estão criados e disponíveis para uso, consulte a página de documentação Bloqueios do Looker. Para informações sobre como personalizar blocos que você instalou do Marketplace, consulte a página de documentação Como personalizar bloqueios do Looker Marketplace.

Para desenvolver um bloco e disponibilizá-lo para 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. Crie um projeto e adicione os arquivos necessários.
  3. Torne seu bloco acessível.
  4. Envie seu bloqueio para revisão do Looker.

Como 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, de fácil repetição. A maioria dos erros de instalação de blocos ocorre quando o conjunto de dados do usuário não corresponde aos nomes do esquema, da tabela e do 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 de dados. 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, observe quais campos você 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 do conjunto de dados. Use constantes 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 seu 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 guia Explorar
  • 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 com 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 do MIT (em inglês).
  • Um arquivo README que detalha as instruções e opções de configuração

Os usuários que instalarem seu bloco poderão refinar as visualizações, os painéis e as visualizações básicos em um arquivo refinements.lkml separado. As seções a seguir explicam cada tipo de arquivo em mais detalhes:

Como criar um arquivo de manifesto

Crie um arquivo de manifesto para seu projeto. O arquivo de manifesto deve começar com um nome de projeto e definir algumas constantes do LookML para os usuários alterarem. 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 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 esquema e tabela de um usuário forem diferentes dos seus, defina os nomes do esquema e da tabela como constantes no arquivo de manifesto para que os usuários que fizerem o download do bloco possam atualizar esses itens 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. Verifique se cada arquivo de exploração inclui as visualizações necessárias para essa exploração. Crie cuidadosamente suas explorações para conter sessões lógicas, exercícios e páginas "Explorar" selecionadas. Depois que outro usuário instala o bloqueio a partir do Marketplace, deve ser simples para seus usuários comerciais acessar e começar a analisar seus dados.

Veja uma lista geral das 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 do LookML e Como criar 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"

  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 constante do LookML 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 do painel do LookML

Para inclusão no Looker Marketplace, cada bloco precisa incluir no mínimo três painéis do LookML que fornecem análises significativas e úteis. Os painéis devem ser estéticos, funcionais e abrangentes, e não devem conter dados desfocados.

Embora não haja requisitos de design rígido 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 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 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 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 para o Redshift do Redshift Admin Block 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 da empresa deve ser exibida no Marketplace. Cada bloco no Looker Marketplace precisa fornecer essas informações adicionais para ajudar os usuários a selecionar o bloco mais adequado às necessidades deles. Seu arquivo marketplace.json deve conter:

  • Campos label, category_label e branding do Marketplace
  • Uma lista de constantes do LookML que precisam ser preenchidas por usuários para preencher o modelo LookML (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 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 ficha do Marketplace que seria gerada por esse arquivo marketplace.json.

Um exemplo de listagem do Marketplace.

  • O campo "label" controla o título do bloco. Neste exemplo, usamos o Desempenho do Google BigQuery.
  • O campo "tagline" controla o primeiro parágrafo da listagem do 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. Neste 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 será solicitado a especificar valores para esses três campos antes da instalação.

Criando um arquivo de 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 desta licença em um arquivo chamado LICENSE. Consulte o arquivo de Licença do bloco de administrador do Redshift para ver um exemplo de 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](#the_autogenerated_manifest_file) ou no arquivo de refinamentos. Consulte o arquivo README do Redshift Admin Block para um exemplo de arquivo README.

Aspectos a serem considerados para seu 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 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 no conjunto de dados do usuário? Em caso negativo, o que o usuário deve mudar?

Arquivos gerados automaticamente

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

  • Um arquivo marketplace_lock.lkml somente leitura que contém informações da ficha da empresa
  • 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 modelo somente leitura que inclua o arquivo de modelo do seu bloco e o arquivo refinements.lkml

Os usuários que instalarem seu bloco do Looker Marketplace poderão usar o arquivo refinements.lkml para refinar o LookML e até adicionar novos arquivos. Consulte a página de documentação Como personalizar bloqueios 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 seu bloco definam variáveis como o nome da conexão. As constantes 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 instalaram seu bloco refinam visualizações e explorações que tenham sido definidos. É 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 bloco acessível

Hospede seu bloco LookML em um repositório do GitHub acessível ao público.

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

Como enviar o bloqueio para análise

Quando o bloqueio estiver pronto para envio, siga as instruções em Enviar conteúdo ao Looker Marketplace para criar a documentação de apoio, enviar o bloqueio para a equipe da Looker analisar e publicar o bloqueio no Looker Marketplace.