Personalizar blocos do Marketplace do Looker

Os Looker Blocks são modelos de dados pré-criados para padrões analíticos e fontes de dados comuns. Esta página descreve como os desenvolvedores podem personalizar os Looker Blocks instalados no Marketplace do Looker. O Looker Marketplace é um local central para encontrar, implantar e gerenciar muitos tipos de conteúdo do Looker, como aplicativos, visualizações e plug-ins.

Para mais informações sobre todos os Looker Blocks disponíveis e métodos alternativos de personalização de blocos, consulte a página de documentação dos Looker Blocks.

Requisitos para instalar e gerenciar Looker Blocks no Marketplace do Looker

Antes de instalar e usar alguns blocos do Marketplace do Looker, observe os seguintes requisitos:

• Se você estiver instalando o bloco pelo Marketplace do Looker, o administrador do Looker precisará ativar o recurso Marketplace.
• Os usuários precisam ter permissões develop, manage_models e deploy para instalar e gerenciar pacotes do Marketplace.

• Se o bloco específico contiver um local_dependency parâmetro, ele usará o processo de importação de projeto local. Consulte a página de documentação Importar arquivos de outros projetos para mais detalhes sobre como importar projetos. Os blocos a seguir contêm um parâmetro local_dependency:

  • Análise de marketing digital
  • Análise de dados de vendas
  • Análise da Web

Consulte a página de documentação do Looker Marketplace para informações sobre como instalar e gerenciar Looker Blocks no Marketplace do Looker.

Como acessar o LookML de um bloco do Marketplace

Os blocos baseados em projetos que usam refinamentos são instalados no Marketplace como um único projeto CONFIG editável que importa remotamente o projeto CORE, que contém todo o código LookML e a parametrização constante.

Depois que um bloco é instalado no Marketplace, é possível acessar o projeto no menu Desenvolver clicando no nome do projeto na lista de projetos. O nome de um bloco de refinamentos do Marketplace geralmente é precedido por marketplace_ seguido pelo ID da listagem.

Embora não seja possível modificar diretamente o projeto CORE somente leitura de um bloco, talvez você queira usar o LookML definido nos arquivos CORE somente leitura do bloco como referência ao personalizar os arquivos CONFIG do bloco. Para conferir os arquivos CORE do bloco, navegue até os arquivos do projeto do bloco no IDE e expanda o imported_projects diretório no navegador de arquivos do IDE.

Estrutura de arquivos de bloco

Ao instalar um bloco criado para refinamentos, esses arquivos são criados automaticamente como parte da parte CONFIG do projeto de bloco:

Nome do arquivo	Acesso	Função
<model_name>.model.lkml	Somente leitura para todos os usuários	Arquivo de modelo "virtual" vinculado à instalação do bloco; processa a importação de modelos do projeto CORE do bloco. Quando um bloco é desinstalado ou atualizado, o arquivo ou arquivos modelo associados são excluídos, evitando conflitos de modelo entre várias instalações de blocos.
manifest.lkml	Editável para usuários com permissões develop	Descreve o projeto e as dependências externas dele. Contém o ID da listagem do Marketplace para a instalação do bloco e facilita a importação remota dos arquivos do projeto CORE do bloco usando a palavra-chave marketplace.
marketplace_lock.lkml	Somente leitura para todos os usuários	Contém uma referência à palavra-chave marketplace_ref do arquivo de manifesto que processa a importação remota do projeto CORE. Fornece as informações específicas de listagem, versão e modelo associadas à instalação. Contém informações sobre constantes configuradas durante a instalação (e que podem ser atualizadas usando a opção Gerenciar na interface do Marketplace).
refinements.lkml	Editável para usuários com permissões develop	Permite que os desenvolvedores refinem visualizações e análises definidas nos arquivos do projeto CORE importado.

Como personalizar um bloco do Marketplace

Ative o modo de desenvolvimento para fazer personalizações nos arquivos editáveis do bloco.

Se você tiver permissões develop, poderá personalizar o LookML no arquivo refinements.lkml do projeto CONFIG do bloco. É possível refinar as visualizações e análises já definidas no projeto CORE do bloco ou até mesmo adicionar novas visualizações e análises que ainda não estão definidas no projeto CORE. Tudo o que é possível com refinamentos do LookML em outros projetos do LookML também é possível no arquivo refinements.lkml do bloco. A combinação do refinamento e do LookML original se comporta como se fosse o LookML original do objeto.

Também é possível fazer mudanças no arquivo manifest.lkml do projeto CONFIG para especificar as dependências que precisam ser capturadas para esse bloco.

Você não está limitado a modificar esses arquivos para conseguir as personalizações desejadas. Também é possível criar novos arquivos no projeto CONFIG. Basta include todos os novos arquivos no arquivo refinements.lkml.

Como personalizar o arquivo de refinamentos

Se você tiver permissões develop, poderá adicionar o LookML personalizado ao projeto CONFIG para misturar dados adicionais ou mudar o modelo analítico principal do bloco. É possível criar novas visualizações e associá-las às análises atuais, definir novos campos ou redefinir campos atuais ou aplicar rótulos conforme necessário para criar um modelo para a análise que você quer fornecer. Se você criou novos arquivos no projeto CONFIG, é necessário include esses arquivos no arquivo de refinamentos.

Por exemplo, digamos que você instalou um bloco e o arquivo refinements.lkml dele contém o seguinte LookML:

include: "//<listing_id>/**/*.view.lkml"
include: "//<listing_id>/**/*.explore.lkml"

em que listing_id é o valor do parâmetro listing do arquivo manifest.lkml.

É possível usar refinamentos para adicionar uma nova dimensão a uma visualização chamada flights:

include: "//<listing_id>/**/*.view.lkml"
include: "//<listing_id>/**/*.explore.lkml"

view: +flights {
  dimension: air_carrier {
    type: string
    sql: ${TABLE}.air_carrier ;;
  }
}

Ou você pode aplicar um rótulo a uma análise chamada aircraft para que ela apareça na UI como Aircraft Simplified:

include: "//<listing_id>/**/*.view.lkml"
include: "//<listing_id>/**/*.explore.lkml"

explore: +aircraft {
  label: "Aircraft Simplified"
}

O arquivo refinements.lkml é incluído automaticamente no arquivo modelo "virtual" do block, que importa os modelos do projeto CORE.

Consulte a documentação de refinamentos do LookML para mais informações sobre esse tópico avançado.

Como personalizar o arquivo de manifesto editável

Em blocos que usam refinamentos, os projetos CORE e CONFIG têm arquivos de manifesto. No entanto, apenas o arquivo de manifesto do projeto CONFIG é editável.

É possível editar o arquivo CONFIG manifest.lkml para adicionar parâmetros de projeto aos que já aparecem no arquivo de manifesto do projeto CORE. Por exemplo, é possível adicionar um local_dependency para associar seu bloco a outro bloco na mesma instância do Looker.

Como atualizar valores de constantes

As constantes do bloco são definidas no arquivo de manifesto do projeto CORE importado. A substituição do valor de uma constante, se permitida, precisa ser feita na interface do Marketplace durante a configuração ou atualizando o bloco. Para atualizar um bloco, os usuários precisam ter permissões develop, manage_models e deploy.

Para substituir o valor de uma constante atualizando um bloco, siga estas etapas:

1. No Marketplace do Looker, navegue até o bloco que você quer atualizar.
2. Clique no botão Gerenciar.
3. Ao lado do nome do bloco que você quer atualizar, clique no ícone de engrenagem. Isso abre a janela de configuração do bloco.
4. Faça mudanças nos valores constantes conforme necessário.
5. Clique em Atualizar para fechar a janela de configuração do bloco e atualizar o bloco com as mudanças.

As mudanças são refletidas no arquivo marketplace_lock.lkml somente leitura no projeto instalado.

Como preservar as personalizações de um bloco do Marketplace que usa extensões

Alguns dos blocos disponíveis no Marketplace do Looker foram compostos de projetos que usam extensões do LookML extends. O Looker está convertendo todos os blocos do Marketplace para instâncias no Looker 21.8 ou mais recente em uma estrutura de projeto que usa refinamentos do LookML e vai remover o suporte para blocos baseados em extensões.

O Looker recomenda que você instale a versão baseada em refinamentos de todos os blocos do Marketplace que você tem na sua instância à medida que esses blocos ficam disponíveis, substituindo os blocos criados com extensões. Embora esse processo de substituição seja simples (é possível instalar o novo bloco de refinamentos na listagem de blocos do Marketplace do Looker e desinstalar o bloco original de extensões na página Gerenciar do Marketplace do Looker), ele não vai preservar nenhuma das personalizações que possam ter sido feitas no bloco criado com extensões. O Looker também não vai transferir nenhum conteúdo ou função do Looker com base nesse conteúdo (painéis, análises, entregas de conteúdo programadas, alertas) do bloco original para o novo bloco.

Esta seção descreve como preservar as personalizações de um bloco criado com projetos que usam extensões que, de outra forma, seriam difíceis ou demoradas para replicar do zero.

Para preservar as personalizações do bloco, um usuário com a capacidade de instalar e gerenciar pacotes do Marketplace precisa seguir estas etapas:

1. Atualizar o projeto CONFIG original do bloco para se preparar para a migração
2. Instalar a nova versão do bloco no Marketplace do Looker
3. Transferir as personalizações para o novo bloco do Marketplace
4. Recriar o conteúdo do Looker com base no bloco original
5. Desinstalar a versão do bloco que foi criada com extensões

Como atualizar um bloco personalizado para se preparar para a migração

Esta seção descreve como atualizar os arquivos de projeto principais em um bloco criado com extensões para que você possa copiar as personalizações do bloco para uma nova versão baseada em refinamentos do bloco. Um bloco baseado em um projeto que usa extensões é instalado no Marketplace como um projeto CORE somente leitura e um projeto CONFIG editável.

1. Navegue até o projeto CONFIG do bloco na seção Desenvolver de uma das seguintes maneiras:

   • Clique na opção Projetos e depois no nome do projeto.
   • Clique no nome do projeto CONFIG do bloco na lista de projetos.

   Os nomes dos projetos CONFIG geralmente terminam em _config, enquanto o nome do projeto CORE normalmente não tem um sufixo.

2. Abra o arquivo modelo do projeto, que pode ser parecido com este:

    explore: ga_sessions_config {
      extends: [ga_sessions_core]
      extension: required
      join: user_sales_data {
        sql_on: ${user_sales_data.full_visitor_id} = ${ga_sessions.full_visitor_id} ;;
      }
      join: sales__by__category {
        sql: LEFT JOIN UNNEST(${user_sales_data.sales_by_category}) as sales__by__category;;
      }
    }

    explore: future_input_config {
      extends: [future_input_core]
      extension: required
      join: future_purchase_prediction {
        type: left_outer
        sql_on: ${future_input.full_visitor_id} = ${future_purchase_prediction.full_visitor_id} ;;
        relationship: one_to_one
      }
    }

1. No modo de desenvolvimento, siga estas etapas:

   1. Exclua as linhas extends e extension inteiras.
   2. Exclua _config dos nomes explore.
   3. Preceda + aos nomes explore.

   O exemplo de arquivo de modelo anterior seria assim:

    explore: +ga_sessions {
      join: user_sales_data {
        sql_on: ${user_sales_data.full_visitor_id} = ${ga_sessions.full_visitor_id} ;;
      }
      join: sales__by__category {
        sql: LEFT JOIN UNNEST(${user_sales_data.sales_by_category}) as sales__by__category;;
      }
    }

    explore: +future_input {
      join: future_purchase_prediction {
        type: left_outer
        sql_on: ${future_input.full_visitor_id} = ${future_purchase_prediction.full_visitor_id} ;;
        relationship: one_to_one
      }
    }

1. Copie e mantenha o conteúdo desse arquivo para uma etapa futura.

Como instalar o novo bloco do Marketplace

Um bloco baseado em um projeto que usa refinamentos é instalado no Marketplace como um único projeto do LookML editável que importa remotamente o projeto que contém todo o LookML e a parametrização constante.

1. Selecione o ícone da loja na barra de menus do Looker para navegar até o Marketplace do Looker.
2. Clique na listagem do novo bloco do Marketplace baseado em refinamentos. Esse bloco tem o mesmo nome do bloco atual criado com extensões.
3. Clique em Instalar para instalar o novo bloco. Depois que esse bloco for instalado, você verá duas listagens idênticas na página Gerenciar do Marketplace do Looker.

Como transferir personalizações para o novo bloco do Marketplace

Esta seção descreve como transferir as atualizações feitas no bloco original (extensões) para o novo bloco (refinamentos).

1. Na seção Desenvolver, abra o projeto do novo bloco de uma das seguintes maneiras:

   • Clique na opção Projetos e depois no nome do projeto.
   • Clique no nome do projeto do bloco na lista de projetos.

   O nome de um bloco de refinamentos do Marketplace geralmente é precedido por marketplace_ seguido pelo ID da listagem.

2. No arquivo refinements.lkml, cole o conteúdo atualizado do arquivo modelo do bloco original (extensões). Mantenha todas as instruções include que já estão no arquivo de refinamentos.

Como recriar o conteúdo do Looker com base no bloco original

A etapa final na adoção da versão baseada em refinamentos de um bloco do Marketplace é desinstalar a versão original baseada em extensões do bloco. Alguns blocos baseados em extensões contêm painéis e análises do LookML pré-criados. Se os usuários tiverem criado alertas ou entregas programadas com base em painéis do LookML definidos no bloco original (extensões), esses alertas ou programações serão desativados ou falharão, respectivamente, depois que o bloco for desinstalado do Marketplace do Looker.

É necessário recriar esses alertas ou entregas programadas nos painéis do LookML do novo bloco (refinamentos). Os administradores e usuários do Looker com as permissões adequadas para programações e alertas podem usar as páginas Alertas e programações na seção de administração para pesquisar os nomes dos painéis do bloco (extensões) e criar novos alertas ou entregas programadas conforme necessário nos painéis correspondentes do bloco (refinamentos).

Você também precisa modificar qualquer outro conteúdo do Looker que faça referência às análises ou painéis do LookML do bloco original (extensões) para apontar para o novo bloco (refinamentos), conforme necessário.

Como desinstalar o bloco original

Para desinstalar a versão do bloco que foi criada com extensões, siga estas etapas:

1. Selecione o ícone da loja na barra de menus do Looker para navegar até o Marketplace do Looker.

2. No Marketplace do Looker, selecione Gerenciar na navegação à esquerda para abrir a página Gerenciar.

3. Na página Gerenciar, clique no ícone da lixeira para desinstalar o bloco original (extensões). É possível diferenciar a lista de blocos de extensões da listagem de blocos de refinamentos observando os números de versão. O bloco de extensões será uma versão principal atrás do bloco de refinamentos. Por exemplo, o bloco de extensões pode ser a versão 1.0.4 e o bloco de refinamentos pode ser a versão 2.0.0.

Observação: depois que o bloco for desinstalado, a listagem de blocos original (extensões) vai desaparecer do painel de navegação principal na instância do Looker, as análises vão desaparecer da seção Analisar, os painéis do LookML vão desaparecer da pasta Painéis do LookML e todos os alertas ou entregas programadas com base nos painéis do LookML do bloco serão desativados ou falharão, respectivamente.

Como resolver problemas de um bloco

Se um bloco do Marketplace mostrar erros, é possível que seu esquema não corresponda à estrutura do bloco.

Talvez você também queira verificar se as constantes fornecidas durante a instalação do bloco, que representam a conexão, o banco de dados ou o esquema do bloco, foram definidas corretamente. Para isso, siga estas etapas:

1. Selecione o ícone da loja na barra de menus do Looker para navegar até o Marketplace do Looker.

2. No Marketplace do Looker, selecione Gerenciar no painel de navegação principal para abrir a página Gerenciar.

3. Na página Gerenciar, clique no ícone de engrenagem do bloco para conferir as configurações de configuração.

4. Na janela Atualizar configurações, confirme se o bloco está configurado corretamente. Clique em Atualizar depois de fazer mudanças para salvar as atualizações e fechar a janela de configuração do bloco.