Como personalizar blocos do Looker Marketplace

O Looker BlocksTM é um modelo de dados pré-criado para padrões de análise e fontes de dados comuns. Nesta página, descrevemos como os desenvolvedores podem personalizar os blocos do Looker que são 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 os blocos que não estão atualmente disponíveis no Looker Marketplace, bem como métodos alternativos de personalização de blocos, consulte a página de documentação Blocos do Looker (link em inglês).

Requisitos para instalar e gerenciar blocos do Looker no Looker Marketplace

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

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

  • Se o bloco específico contiver um parâmetro local_dependency, seu administrador do Looker também precisará ativar o recurso de Labs de importação de projetos locais do 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 no Marketplace.

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

Como acessar o LookML para 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.

Quando um bloco for instalado no Marketplace, você poderá acessar o projeto no menu Desenvolver clicando no nome do projeto na lista de projetos. Normalmente, o nome de um bloco de refinamentos do Marketplace é anexado com marketplace_ seguido pelo ID da ficha da empresa.

Embora não seja possível modificar diretamente um projeto CORE somente leitura de um bloco, recomendamos usar o LookML definido nos arquivos CORE somente leitura do bloco como referência ao personalizar os arquivos de CONFIGURAÇÃO de bloco. Para ver os arquivos CORE do bloco, acesse os arquivos do 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 a estrutura de arquivos

Quando você instala 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 qualquer modelo do projeto CORE 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 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 da listagem do Marketplace para a instalação em blocos e facilita a importação remota dos arquivos de 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 do modelo específicas 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 IU do Marketplace).
refinements.lkml Editável para usuários com permissões develop Permite que os desenvolvedores refinem as visualizações e os explorações definidos nos arquivos de projeto CORE importados.

Como personalizar um bloco do Marketplace

Ative o Modo de desenvolvimento para personalizar os arquivos editáveis dos blocos.

Se você tiver permissões develop, poderá personalizar o LookML no arquivo refinements.lkml do projeto CONFIG do Block' 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 que ainda não estão definidas no projeto CORE. Tudo o que é possível com refinamentos do LookML em outros projetos LookML é possível no arquivo refinements.lkml do bloco. A combinação do refinamento e o 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.

Não é necessário modificar esses arquivos para atender às personalizações desejadas. Também é possível criar novos arquivos no projeto CONFIG. No entanto, lembre-se de include adicionar os novos arquivos no refinements.lkml.

Como personalizar o arquivo de refinamentos

Se você tiver permissões develop, poderá adicionar LookML personalizado ao projeto CONFIG para adicionar outros dados ou alterar o modelo analítico principal do bloco. É possível criar novas visualizações e agrupá-las a "explores" atuais, definir novos campos ou redefinir campos existentes ou aplicar rótulos conforme necessário e criar um modelo para a análise a ser fornecida. Se você tiver criado novos arquivos no projeto CONFIGUR, precisará include esses arquivos 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 exploração chamada aircraft, para que ela apareça na IU 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 de blocos "virtual", que importa basicamente os modelos do projeto CORE.

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

Personalizar o arquivo de manifesto editável

Nos 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 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 uma local_dependency para mesclar seu bloco em outro na mesma instância do Looker.

Antes de você usar ou criar em um bloco que contenha um parâmetro local_dependency, um administrador do Looker precisa ativar o recurso de Labs de importação de projetos locais do Labs.

Como atualizar valores de constantes

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

Para substituir um valor de 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 engrenagem. A janela de configuração de bloqueio é aberta.
  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 bloqueio com as suas 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-se

Alguns dos bloqueios disponíveis no Looker Marketplace foram compostos por projetos que usam estendidas do LookML. 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 bloqueios com base em estendimentos.

O Looker recomenda a instalação da versão baseada em refinamentos de qualquer bloco do Marketplace que você tiver em sua instância, à medida que esses blocos forem disponibilizados, substituindo os blocos criados por estende-se. Embora esse processo de substituição seja simples, você pode instalar o novo bloco (refinamentos) da lista de bloqueio do Looker Marketplace e desinstalar o bloco original (extensão) na página Gerenciar do Looker Marketplace. Ele não preserva as personalizações que podem ter sido feitas no bloco que foi construído com a extensão. O Looker também não transfere conteúdo ou funções do Looker baseados nesse conteúdo (painéis, Explorars, entregas de conteúdo programada, alertas) do bloco original para o novo bloco.

Esta seção descreve como preservar quaisquer personalizações em um bloco criado com projetos que usam extensões que, do contrário, seriam difíceis ou demorados de 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 de configuração do bloco original para se preparar para a migração
  2. Instale a nova versão do bloco pelo 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 extensão

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

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

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

    • Clique na opção Projetos e no nome do projeto.
    • Clique no nome do projeto CONFIGUR 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 do 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 explore.
    3. Inclua + aos nomes de 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 retenha o conteúdo desse arquivo para uma etapa futura.

Como instalar o novo bloco do Marketplace

Consulte os Destaques da versão do Looker 21 para mais informações sobre quais bloqueios já passaram pela conversão em refinamentos. É possível diferenciar a lista de bloqueio de estendidos da lista de bloqueio de refinamentos observando os números de versão. O bloco de extensões será uma versão principal por trá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.

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

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

Transferir personalizações para o novo bloco do Marketplace

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

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

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

    Normalmente, o nome de um bloco de refinamentos do Marketplace é anexado com marketplace_ seguido pelo ID da ficha da empresa.

  2. No arquivo refinements.lkml, cole o conteúdo atualizado do arquivo de modelo original do bloco (estenda). Mantenha 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 estendes do bloco. Alguns blocos baseados em extensão 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 (estendimento), esses alertas ou programações serão desativados ou falharão, respectivamente, quando o bloco for desinstalado do Looker Marketplace.

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

Você também precisa modificar qualquer conteúdo do Looker que faça referência aos blocos "Explorar" ou "LookML" originais (estenda) para apontar para o novo bloco (refinamentos), conforme necessário.

Desinstalando o bloco original

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

  1. Selecione o ícone de compra na barra de menus do Looker para navegar até 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 (estenda). É possível diferenciar a lista de bloqueio de estendidos da lista de bloqueio de refinamentos observando os números de versão. O bloco de extensões será uma versão principal por trá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.

Depois que o bloco é desinstalado, a lista de bloqueio original (endenda) desaparece da navegação à esquerda na instância do Looker, os explorações desaparecem da seção Explorar, os painéis do LookML desaparecem da pasta LookML painéis e todos os alertas ou entregas programadas que são baseadas no bloco do LookML do bloco são desativados ou falham, respectivamente.

Solução de problemas em 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 de compra na barra de menus do Looker para navegar até 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 Update settings, confirme se o bloqueio está configurado corretamente. Clique em Atualizar após fazer as alterações para salvar as atualizações e fechar a janela de configuração do bloco.