Como personalizar blocos do Looker Marketplace

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

Para mais informações sobre todos os blocos do Looker disponíveis, incluindo aqueles que ainda não estão disponíveis no Marketplace do Looker, bem como métodos alternativos de personalização de blocos, consulte a página de documentação Blocos do Looker.

Requisitos para instalar e gerenciar o Looker Blocks no Marketplace do Looker

Antes de instalar e usar alguns blocos do Marketplace do Looker, seu administrador precisa ativar estes recursos:

• Se você estiver instalando o bloco pelo Looker Marketplace, o administrador da ferramenta vai precisar ativar o recurso Marketplace.

• Se o bloco específico tiver um parâmetro local_dependency, o administrador do Looker também vai precisar ativar o recurso de Importação de projetos locais Labs. Esses blocos contêm um parâmetro local_dependency:

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

Os usuários precisam ter as permissões develop, manage_models e deploy para instalar e gerenciar pacotes do Marketplace.

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

Como acessar o LookML em um bloco do Marketplace

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

Depois que um bloco for instalado pelo Marketplace, você vai poder acessar o projeto no menu Desenvolver. Para isso, clique no nome dele na lista. O nome de um bloco de refinamentos do Marketplace geralmente é precedido por marketplace_ seguido pelo ID da ficha da empresa.

Embora não seja possível modificar diretamente o projeto CORE somente leitura de um bloco, é possível usar o LookML definido nos arquivos CORE somente leitura do bloco como uma referência ao personalizar os arquivos CONFIG do bloco. Você pode conferir os arquivos CORE do bloco navegando até os arquivos do projeto do bloco no ambiente de desenvolvimento integrado e expandindo o diretório imported_projects no navegador de arquivos do ambiente de desenvolvimento integrado.

Bloquear estrutura do arquivo

Quando você instala um bloco que é 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. Ele lida com a importação de qualquer modelo do projeto PRINCIPAL do bloco. Quando um bloco é desinstalado ou atualizado, os arquivos de modelo associados são excluídos, evitando conflitos de modelo entre várias instalações em bloco.
manifest.lkml	Editável para usuários com permissões develop	Descreve o projeto e as dependências externas. Contém o ID de listagem do Marketplace para a instalação do bloco e facilita a importação remota dos arquivos do projeto CORE do bloco por meio da 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. Mostra informações específicas da 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 de projeto CORE importados.

Como personalizar um bloco do Marketplace

Ative o Modo de desenvolvimento para personalizar os 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 adicionar novas visualizações e Análises que ainda não estejam definidas no projeto CORE. Tudo o que é possível com os refinamentos do LookML em outros projetos do LookML é 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.

Você também pode 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 precisa modificar esses arquivos para obter as personalizações desejadas. Também é possível criar novos arquivos no projeto CONFIG. Lembre-se de include adicionar todos os arquivos novos no refinements.lkml.

Personalizar o arquivo de refinamentos

Se você tiver permissões develop, é possível adicionar o LookML personalizado ao projeto CONFIG para misturar outros dados ou mudar o modelo analítico principal do bloco. É possível criar novas visualizações e mesclá-las a Análises atuais, definir novos campos, redefinir campos 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, você precisa solicitá-los include no arquivo de refinamentos.

Por exemplo, digamos que você tenha instalado um bloco e o arquivo refinements.lkml dele contenha:

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

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

Você pode 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 ;;
  }
}

Também é possível aplicar um rótulo a uma Análise chamada aircraft para que ela apareça na UI como Aeronave simplificada:

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

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

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

Consulte a documentação Refinamentos do LookML para mais informações sobre este 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, somente o arquivo de manifesto do projeto CONFIG é editável.

Você pode editar o arquivo CONFIG manifest.lkml para adicionar parâmetros do projeto àqueles que já aparecem no arquivo de manifesto do projeto CORE. Por exemplo, você pode adicionar uma local_dependency para join seu bloco a outro na mesma instância do Looker.

Antes de usar ou criar em um bloco que contém um parâmetro local_dependency, um administrador do Looker precisa ativar o recurso Importação de projetos locais Labs.

Como atualizar valores para constantes

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

Para substituir o valor de uma constante atualizando um bloco:

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. Mude os 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 do projeto instalado.

Preservar as personalizações de um bloco do Marketplace que usa estende

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

O Looker recomenda que você instale a versão baseada em refinamentos de todos os blocos do Marketplace que você tiver na sua instância conforme eles forem disponibilizados, substituindo blocos criados por extensões. O processo de substituição é simples, mas você pode instalar o novo bloco (refinamentos) na página de detalhes do Bloco do Looker Marketplace e desinstalar o bloco original (estende) na página Gerenciar no Marketplace do Looker. No entanto, as personalizações feitas no bloco criado com extensões não serão preservadas. O Looker também não transfere nenhum conteúdo ou funções do Looker com base nele, como painéis, Análises, envios de conteúdo programados e alertas, do bloco original para o novo.

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:

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

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

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

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

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

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

2. Abra o arquivo de modelo do projeto, que pode ter esta aparência:

    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:

   1. Exclua todas as linhas extends e extension.
   2. Exclua _config dos nomes de explore.
   3. Use o prefixo + nos nomes de explore.

   O exemplo anterior do arquivo de modelo ficaria 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 guarde 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 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 existente que foi criado com extensões.
3. Clique em Instalar para instalar o novo bloco. Depois da instalação, você vai encontrar duas fichas idênticas na página Gerenciar do Marketplace do Looker.

Transferindo personalizações para o novo bloco do Marketplace

Esta seção descreve como transferir as atualizações feitas no bloco original (estende) 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 ficha da empresa.

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

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

A etapa final para adotar a 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 dashboards do LookML e Explores pré-criados. Se os usuários tiverem criado alertas ou entregas programadas com base em painéis do LookML definidos no bloco original (estende), esses alertas ou as programações vão ser desativados ou falharão, respectivamente, quando o bloco for desinstalado do Marketplace do Looker.

Você precisa 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 "Administrador" para pesquisar os nomes dos painéis do bloco (estende) 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 aos painéis Explores ou LookML do bloco original (estende) para apontar para o novo bloco (refinamentos), conforme necessário.

Como desinstalar o bloco original

Para desinstalar a versão do bloco que foi criado com extensões:

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 menu de navegação à esquerda para abrir a página Gerenciar.

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

Depois que o bloco for desinstalado, a listagem de bloco original (estende) vai desaparecer da navegação à esquerda na instância do Looker, os Explores desaparecerão da seção Explore, os dashboards do LookML vão desaparecer da pasta LookML dashboards. Além disso, todos os alertas ou entregas programadas baseados nos dashboards do LookML do bloco serão desativados ou falharão, respectivamente.

Solução de problemas em um bloco

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

Confira também se as constants fornecidas durante a instalação do bloco que representam a conexão, o banco de dados ou o esquema dele foram definidas corretamente. Para isso, você pode:

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 menu de navegação à esquerda para abrir a página Gerenciar.

3. Na página Gerenciar, clique no ícone de engrenagem do bloco para ver 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 qualquer mudança para salvar as atualizações e feche a janela de configuração de bloqueio.