Desenvolver um bloco personalizado para o Looker Marketplace

Esta página descreve como criar um bloco personalizado que pode ser adicionado ao Looker Marketplace e acedido por outros utilizadores do Looker.

Tenha em atenção que tem de ser membro da Looker Partner Network ou cliente do Looker para enviar conteúdo para o Looker Marketplace.

Para obter informações sobre os blocos do Looker já criados e disponíveis para utilização, consulte a página de documentação Blocos do Looker. Para obter informações sobre a personalização de blocos que instalou a partir do Marketplace, consulte a página de documentação Personalizar blocos do Looker Marketplace.

Para desenvolver um bloco e disponibilizá-lo a todos os utilizadores do Looker através do Looker Marketplace, siga os passos descritos nesta página:

  1. Configure e associe a origem de dados ao Looker.
  2. Crie um projeto e adicione os ficheiros necessários.
  3. Torne o seu bloco acessível.
  4. Envie o bloco para revisão do Looker.

Configurar e associar a origem de dados ao Looker

Os blocos são modelos de dados, pelo que funcionam melhor quando são concebidos para um conjunto de dados específico e facilmente repetível. A maioria dos erros de instalação de blocos ocorre quando o conjunto de dados do utilizador não corresponde ao esquema, à tabela e aos nomes dos campos no bloco.

  • Se estiver a criar um bloco para um conjunto de dados específico, como dados do Google Analytics, tome nota de todas as definições ou personalizações que fez ao conjunto de dados. Sempre que possível, mantenha estas personalizações ao mínimo para simplificar a instalação para os seus utilizadores. Forneça instruções específicas num ficheiro README.
  • Se estiver a criar um bloco para um padrão analítico geral, como a retenção de coortes, tenha em atenção os campos que espera que o conjunto de dados do utilizador contenha. Muito provavelmente, os seus utilizadores não vão ter o mesmo esquema, tabela e nomes de campos que no seu conjunto de dados. Use constantes do LookML para nomes de tabelas e campos, e informe o utilizador dos campos que tem de atualizar num ficheiro README.

Depois de determinar a sua origem de dados, associe-a ao Looker para poder começar a modelar. Se precisar de alterar alguma das definições de ligação predefinidas, tome nota no seu ficheiro README.

Criar um projeto e adicionar os ficheiros necessários

Crie um projeto para representar o seu bloco. Considere usar uma convenção de nomenclatura, como block-<database_dialect>-<role> (por exemplo, block-redshift-admin).

Em seguida, crie os seguintes ficheiros no seu projeto:

  • Um ficheiro de manifesto que define o nome do projeto, o nome da ligação e quaisquer outras constantes
  • Um ficheiro de visualização para cada visualização
  • Um ficheiro de exploração para cada exploração
  • Um ficheiro de modelo que inclui todos os ficheiros de visualização, ficheiros de exploração e ficheiros de painel de controlo do LookML no projeto
  • Pelo menos, três ficheiros de painel de controlo do LookML
  • Um ficheiro marketplace.json que contém informações que vão ser apresentadas na ficha do Marketplace para este bloco
  • Um ficheiro LICENSE que inclui o texto da licença de código aberto MIT
  • Um ficheiro README que detalha as instruções e as opções de configuração

Os utilizadores que instalam o seu bloco podem refinar as explorações, as vistas e os painéis de controlo base num ficheiro refinements.lkmlseparado. As secções seguintes explicam cada tipo de ficheiro obrigatório mais detalhadamente:

Criar um ficheiro de manifesto

Crie um ficheiro de manifesto para o seu projeto. O ficheiro de manifesto deve começar com um nome do projeto e, em seguida, definir algumas constantes LookML para os utilizadores alterarem. Por exemplo, deve definir o nome da ligação do Looker como uma constante com export: override_required para que os utilizadores possam substituí-lo pelo respetivo nome da ligação.

Segue-se um exemplo de um ficheiro 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
}

Criar ficheiros de vista e de exploração

Crie um ficheiro view.lkml para cada vista. Se os nomes de esquemas e tabelas de um utilizador puderem diferir dos seus, certifique-se de que define os nomes de esquemas e tabelas como constantes no seu ficheiro de manifesto para que os utilizadores que transfiram o seu bloco possam atualizar os nomes de esquemas e tabelas no ficheiro de manifesto gerado automaticamente. Em seguida, faça referência a essas constantes nos parâmetros sql_table_name das suas visualizações.

Segue-se um exemplo de um ficheiro de bloqueio view.lkml:

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 ficheiros explore.lkml. Certifique-se de que cada ficheiro de exploração inclui as visualizações necessárias para essa exploração. Conceba os seus Explorar cuidadosamente para conter junções lógicas, detalhamentos e páginas do Explorar organizadas. Depois de outro utilizador instalar o bloco a partir do Marketplace, os utilizadores empresariais devem poder começar a analisar os respetivos dados de forma simples.

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 no LookML e Prática recomendada: escrever LookML sustentável e de fácil manutenção.

Segue-se um exemplo de um ficheiro 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
  }
}

Criar um ficheiro do modelo

Crie um ficheiro do modelo que inclua todos os ficheiros de vista, exploração e painel de controlo no seu projeto. Certifique-se de que o nome da ligação é referenciado como uma constante LookML do seu ficheiro de manifesto.

Defina, pelo menos, um datagroup para definir uma política de colocação em cache.

Segue-se um exemplo de um ficheiro 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;;
}

Criar ficheiros de painéis de controlo do LookML

Para inclusão no mercado do Looker, cada bloco tem de incluir, no mínimo, três painéis de controlo do LookML que forneçam uma análise útil e significativa. Os painéis de controlo devem ser estéticos, funcionais e abrangentes, e não devem apresentar dados esbatidos.

Embora não existam requisitos de design rígidos para os painéis de controlo do LookML, o Looker recomenda estas práticas recomendadas de design geral:

  • Paleta de cores consistente em todo o painel de controlo
  • Pelo menos sete mosaicos
  • Um mínimo de três tipos de visualização diferentes (por exemplo, valor único, barra e linha)

As visualizações personalizadas não são suportadas quando desenvolve painéis de controlo para blocos. Em alternativa, use os tipos de visualização nativos do Looker.

Consulte as páginas de documentação Parâmetros do painel de controlo e Parâmetros dos elementos do painel de controlo para obter mais informações sobre a personalização dos painéis de controlo LookML e das visualizações nos painéis de controlo LookML, respetivamente. Consulte o ficheiro do painel de controlo do LookML de administrador do Redshift do bloco de administrador do Redshift para ver um exemplo de um ficheiro do painel de controlo do LookML.

Criar um ficheiro marketplace.json

Crie um ficheiro marketplace.json para fornecer informações sobre como a ficha deve ser apresentada no Marketplace. Cada bloco no mercado do Looker tem de fornecer estas informações adicionais para ajudar os utilizadores a selecionar o bloco que melhor se adapta às suas necessidades. O ficheiro marketplace.json deve conter:

  • Campos label, category_label e branding do Marketplace
  • Uma lista de constantes do LookML que os utilizadores têm de preencher para preencher o LookML do modelo (por exemplo, nomes de ligações)

Segue-se um exemplo de um ficheiro 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 ecrã seguinte mostra a ficha do Marketplace que seria gerada por este ficheiro marketplace.json.

Um exemplo de ficha do Marketplace.

  • O campo "label" controla o título do bloco. Neste exemplo, trata-se do desempenho do Google BigQuery.
  • O campo "tagline" controla o primeiro parágrafo da ficha do Marketplace.
  • O campo "image_uri" controla a imagem apresentada no canto superior esquerdo da ficha do Marketplace. Neste exemplo, é o logótipo do Google Cloud.
  • O campo "constants" pede aos utilizadores que preencham as respetivas constantes na IU do Marketplace durante o processo de instalação. Neste exemplo, são apresentadas três constantes no ficheiro marketplace.json (CONNECTION_NAME, SCHEMA_NAME e AUDIT_LOG_EXPORT_TABLE_NAME), pelo que é pedido ao utilizador que especifique valores para esses três campos antes da instalação.

Criar um ficheiro LICENSE

Todos os Looker Blocks têm de ser licenciados ao abrigo da licença de código aberto do MIT. Inclua o texto desta licença num ficheiro denominado LICENSE. Consulte o ficheiro LICENSE do bloco de administração do Redshift para ver um exemplo de um ficheiro LICENSE.

Criar um ficheiro README

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

Aspetos a considerar para o ficheiro README:

  • De que origem de dados precisa o utilizador? Têm de pagar uma subscrição?
  • Que autorizações deve ter o utilizador da base de dados?
  • Que definições de ligação do Looker são necessárias?
  • Os nomes dos campos de bloqueio correspondem aos nomes dos campos no conjunto de dados do utilizador? Caso contrário, o que deve o utilizador alterar?

Ficheiros gerados automaticamente

Quando os utilizadores instalam o seu bloco, a respetiva instância do Looker cria um novo projeto do Looker com os ficheiros do seu projeto como ficheiros só de leitura. Também gera automaticamente os seguintes ficheiros para o utilizador:

  • Um ficheiro marketplace_lock.lkml só de leitura que contém informações da ficha do mercado
  • Um ficheiro de manifesto que faz referência à ficha de marketplace_lock.lkml
  • Um ficheiro refinements.lkml que inclui todas as visualizações e explorações do seu bloco
  • Um ficheiro de modelo de leitura que inclui o ficheiro de modelo do seu bloco e o ficheiro refinements.lkml

Os utilizadores que instalarem o seu bloco a partir do Looker Marketplace podem usar o ficheiro refinements.lkml para refinar o seu LookML e podem até adicionar novos ficheiros LookML. Consulte a página de documentação Personalizar blocos do Looker Marketplace para mais informações sobre como os utilizadores podem personalizar o seu bloco.

O ficheiro de manifesto gerado automaticamente

O ficheiro de manifesto gerado automaticamente permite que os utilizadores que instalam o seu bloco definam variáveis, como o nome da ligação. As constantes LookML definidas no ficheiro de manifesto do bloco podem ser editadas no ficheiro de manifesto gerado automaticamente ou definidas pelos utilizadores na interface do utilizador de transferência de blocos.

O ficheiro de refinamentos

O ficheiro refinements.lkml gerado automaticamente permite que os utilizadores que instalam o seu bloco refinem as visualizações e as explorações definidas no seu bloco. É aqui que os utilizadores que transferem o seu bloco fazem a maior parte da personalização do LookML para se adequar ao respetivo exemplo de utilização.

Segue-se um exemplo de um ficheiro 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 blocos acessível

Alojamento do seu bloco LookML num repositório do GitHub acessível publicamente.

Todos os Looker Blocks têm de ser licenciados ao abrigo da licença de código aberto do MIT, e o texto da licença tem de ser incluído num ficheiro LICENSE no repositório.

Enviar o bloqueio para revisão

Quando o bloco estiver pronto para envio, siga as instruções em Enviar conteúdo para o mercado do Looker para criar documentação de apoio para o bloco, enviar o bloco para a equipa do Looker para revisão e publicar o bloco no mercado do Looker.