Como personalizar blocos do Looker Marketplace

O Looker BlocksTM é um modelo de dados pré-criado para padrões analíticos comuns e fontes de dados. Nesta página, descrevemos como os desenvolvedores podem personalizar os Looker Lookers instalados do Looker Marketplace. O Looker Marketplace é 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 não estão disponíveis no Looker Marketplace no momento, e métodos alternativos de personalização de blocos, consulte a página de documentação do Looker Blocks.

Requisitos para instalar e gerenciar o Looker Blocks no Looker Marketplace

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

• Se você estiver instalando seu bloco pelo Looker Marketplace, o administrador do Looker precisa ativar o recurso Marketplace.

• Se o bloco específico tiver um parâmetro local_dependency, o administrador do Looker também precisará ativar o recurso Local Project Import 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 ver informações sobre como instalar e gerenciar blocos do Looker Marketplace.

Como acessar o LookML para um bloco do Marketplace

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

Depois que um bloco é instalado a partir do Marketplace, é possível acessar o projeto no menu Desenvolver clicando 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, você pode usar o LookML definido nos arquivos CORE somente leitura do bloco como referência ao personalizar os arquivos CONFIG do bloco. Para ver os arquivos CORE do bloco, navegue até os arquivos de projeto do bloco no ambiente de desenvolvimento integrado e expanda o diretório imported_projects no navegador de arquivos do ambiente de desenvolvimento integrado.

Bloquear estrutura do arquivo

Quando você instala um bloco criado para refinamentos, esses arquivos são criados automaticamente como parte da parte CONFIG do projeto de blocos:

Nome do arquivo	Acesso	Função
<model_name>.model.lkml	Somente leitura para todos os usuários	Arquivo de modelo virtual que está vinculado à instalação do bloco. Processa a importação de qualquer modelo do projeto CORE do bloco. Quando um bloco é desinstalado ou atualizado, os arquivos de modelo associados são excluídos, impedindo conflitos de modelo entre várias instalações de bloco.
manifest.lkml	Editável para usuários com permissões develop	Descreve o projeto e as dependências externas dele. 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. Fornece a listagem, a versão e as informações de modelo específicas associadas à instalação. Contém informações sobre constantes configuradas durante a instalação (e que podem ser atualizadas com a opção Gerenciar na IU do Marketplace).
refinements.lkml	Editável para usuários com permissões develop	Permite que os desenvolvedores refinem visualizações e explorações definidos nos arquivos do 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. Você pode refinar as visualizações e as explorações que já estão definidas no projeto CORE do bloco ou até mesmo adicionar novas visualizações e explorações ainda não definidas no projeto CORE. Qualquer ação possível com 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.

Também é possível fazer alterações 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. include Adicione novos arquivos no arquivo refinements.lkml.

Como personalizar o arquivo de refinamentos

Se você tiver permissões develop, poderá adicionar LookML personalizado ao projeto CONFIG para combinar dados adicionais ou alterar o modelo analítico principal do bloco. É possível criar novas visualizações e associá-las a explorações existentes, definir novos campos ou redefinir campos existentes ou aplicar rótulos conforme necessário para criar um modelo para a análise que você quer fornecer. Se você tiver criado novos arquivos no projeto CONFIGURAR, precisará include no arquivo de refinamento.

Por exemplo, digamos que você tenha instalado um bloco e o arquivo refinements.lkml 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 exploração chamada aircraft para que ela apareça na UI como Aircraft simplificado:

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

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

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

Consulte a documentação sobre 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, somente o arquivo de manifesto do projeto CONFIG é editável.

É possível editar o arquivo de configuração manifest.lkml para adicionar parâmetros do projeto àqueles que já aparecem no arquivo de manifesto do projeto CORE. Por exemplo, é possível adicionar uma local_dependency para mesclar seu bloco com outro na mesma instância do Looker.

Antes de usar ou bloquear um bloco que contenha um parâmetro local_dependency, um administrador do Looker precisa ativar o recurso de Labs do projeto local Labs.

Como atualizar valores para 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 permitido, precisa ser feita na IU do Marketplace durante a configuração ou pela atualização do 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 Looker Marketplace, 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 roda dentada. Isso abre a janela de configuração de bloqueio.
4. Faça alterações nos valores constantes conforme necessário.
5. Clique em Atualizar para fechar a janela de configuração de bloqueio e atualizar o bloqueio com as alterações.

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

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

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

O Looker recomenda que você instale a versão baseada em refinamentos de qualquer bloco do Marketplace que você tiver na sua instância à medida que esses blocos forem disponibilizados, substituindo os blocos criados por estendidos. Esse processo de substituição é simples: você pode instalar o novo bloco (refinamentos) na ficha da empresa do Looker Marketplace e desinstalar o bloco original (estendimentos) na página Gerenciar do Looker Marketplace. Ele não preserva as personalizações feitas no bloco criado. A Looker também não transfere conteúdo nem funções do Looker com base nesse conteúdo (painéis, Explorars, entregas de conteúdo programadas, alertas) do bloco original para o novo bloco.

Esta seção descreve como preservar personalizações em um bloco criado com projetos que usam extensões que, caso contrário, seriam difíceis ou demoradas para replicar do zero.

Para preservar as personalizações de bloqueio, 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. Instale a nova versão do bloco no Looker Marketplace.
3. Transferir 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 a extensão

Atualizando um bloco personalizado para se preparar para a migração

Esta seção descreve como atualizar os principais arquivos de projetos em um bloco que foi construído para 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 estende é 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 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 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 as linhas extends e extension inteiras.
   2. Exclua _config dos nomes de explore.
   3. Use o prefixo + nos nomes de explore.

   O exemplo de arquivo de modelo anterior 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 retenha 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 a partir do Marketplace como um projeto LookML único e editável que importa remotamente o projeto que contém todos os LookML e parametrização constante.

1. Selecione o ícone da loja na barra de menus do Looker para acessar o Looker Marketplace.
2. Clique na listagem para o novo bloco de Marketplace baseado em refinamentos. Esse bloco tem o mesmo nome do bloco existente em que foi construído.
3. Clique em Instalar para instalar o novo bloco. Depois que o bloqueio for instalado, você verá duas listagens idênticas na página Gerenciar do Looker Marketplace.

Transferindo personalizações para o novo bloco do Marketplace

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

1. Na seção Develop, 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 (estenda). Guarde todas as instruções include que já estão no arquivo de refinamento.

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

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

É necessário recriar esses alertas ou entregas programadas nos painéis 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 (estendimentos) 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 "Explorar" ou LookML do bloco original (estenda) para apontar para o novo bloco (refinamentos), conforme necessário.

Desinstalação do bloco original

Para desinstalar a versão do bloco que foi criada, estende-se:

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

2. No Looker Marketplace, selecione Gerenciar na 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ão da lista de bloqueio de refinamentos observando os números de versão. O bloco de extensão será uma versão principal do bloco de refinamentos. Por exemplo, o bloco de extensão 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 é desinstalado, a lista de blocos original (estenda) desaparece da navegação à esquerda na instância do Looker, as explorações desaparecem da seção Explorar, os painéis do LookML desaparecem da pasta LookML painéis e todos os alertas ou exibições programadas com base nos painéis do LookML do bloco são desativados ou falham, respectivamente.

Solução de problemas com blocos

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

Também é possível verificar se as constantes que foram fornecidas durante a instalação do bloco, representando a conexão, o banco de dados ou o esquema do bloco, foram definidas corretamente. Para isso, você pode:

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

2. No Looker Marketplace, selecione Gerenciar na 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.

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