Como importar arquivos de outros projetos

É possível importar arquivos de outros projetos do LookML e repositórios externos para seu projeto atual. Isso permite que você use arquivos de modelo, arquivos de visualização e outros arquivos em mais de um projeto.

Há vários casos de uso para isso. Alguns exemplos:

  • Criar em um bloco do Looker instalado sem precisar fazer alterações diretas nele. Se o Looker fizer alterações no bloco, você poderá extraí-las porque todo o LookML adicionado a ele fica em um repositório separado.

  • Manter um projeto base que é gerado automaticamente com base no esquema do banco de dados. Você pode colocar todas as dimensões, medidas e outros itens personalizados em um projeto separado que importe todo o LookML do projeto gerado automaticamente. É possível gerar novamente o projeto base regularmente conforme o esquema do banco de dados for alterado sem substituir todo o LookML personalizado.

  • Encapsular objetos compartilhados em um único projeto e, em seguida, importá-los para vários outros projetos. Por exemplo, se você tiver uma tabela comum a vários bancos de dados, poderá colocar a visualização dela em um projeto e mantê-la nesse local. Em seguida, importe a tabela para que vários outros projetos possam usá-la.

Para importar arquivos de outro projeto, execute as seguintes tarefas:

  1. Crie um arquivo de manifesto do projeto.
  2. Especifique os projetos locais ou remotos que você quer importar.
  3. Veja os arquivos de um projeto importado.
  4. Incluir arquivos de um projeto importado.

Em seguida, você poderá referenciar campos dos arquivos do projeto importado e substituir os valores das constantes definidos no projeto importado, se as constantes permitirem a substituição.

Como criar um arquivo de manifesto de projeto

Qualquer projeto que importe arquivos de outros projetos precisa ter um arquivo de manifesto de projeto. Se o projeto ainda não tiver um arquivo de manifesto, crie um usando o ícone + na parte de cima do navegador de arquivos no ambiente de desenvolvimento integrado do Looker.

Para importar projetos, especifique-os no manifesto. É possível especificar projetos locais ou remotos, conforme descrito nas seções a seguir.

Como importar projetos locais

A importação de projetos locais só pode ser usada se o projeto importado estiver presente na mesma instância do Looker. Também é recomendado que os desenvolvedores tenham permissões de modelo para os modelos do projeto importado. Se os desenvolvedores tiverem permissões de modelo no projeto importado, o controle de versão será dinâmico, ou seja, as mudanças no projeto importado vão afetar imediatamente o projeto que o importa. Isso permite que os desenvolvedores validem as mudanças nos dois projetos antes de enviar para produção. Além disso, para desenvolvedores com permissões de modelo nos dois projetos, os arquivos de projeto importados vão refletir o status do Modo de desenvolvimento do desenvolvedor. Portanto, se o desenvolvedor estiver no modo de desenvolvimento, o ambiente de desenvolvimento integrado do Looker vai mostrar o modo de desenvolvimento dos arquivos do projeto importado. Se o desenvolvedor estiver no modo de produção, o ambiente de desenvolvimento integrado do Looker vai mostrar o modo de produção do projeto importado.

No arquivo de manifesto, o parâmetro project_name especifica o nome do projeto atual. O Looker preenche esse parâmetro automaticamente quando você cria o arquivo de manifesto do projeto. Para importar um projeto local para o projeto atual, use um ou mais parâmetros local_dependency para especificar os projetos a serem importados:

# This project
project_name: "my_project"

# The project to import
local_dependency: {
  project: "my_other_project"
}

Nos cenários a seguir, use a importação de projeto remoto em vez da importação de projeto local:

  • Seus desenvolvedores não têm permissões de modelo nos modelos do projeto importado. Nesse caso, o Looker clona o Modo de Produção do projeto importado e mostra essa versão estática dos arquivos no ambiente de desenvolvimento integrado. Essa versão estática nunca mostraria a versão do Modo de desenvolvimento dos arquivos e também pode estar desatualizada em relação ao Modo de Produção atual sem alertar o desenvolvedor. Seria melhor usar a importação de projeto remoto e fornecer um ref que especifique uma ramificação ou uma versão do Git no projeto remoto. Se você fizer isso, o Looker detectará automaticamente novas confirmações no projeto remoto para que os desenvolvedores sejam alertados e possam usar a versão mais recente dos arquivos do projeto remoto.
  • Os desenvolvedores precisam trabalhar sempre com a versão de produção de um projeto importado.
  • Os desenvolvedores precisam trabalhar com uma versão estática dos arquivos do projeto importado.

Importação de projetos remotos

Em uma importação remota, o projeto importado não precisa estar na mesma instância. Em vez disso, o projeto é importado pelo repositório Git remoto.

Para importar um repositório remoto, use o parâmetro remote_dependency e forneça as informações dele. O parâmetro remote_dependency usa as seguintes informações e subparâmetros:

  • O nome do projeto importado, que pode ser o que você quiser. No exemplo abaixo, o nome do projeto é ga_360_block. Use esse nome em instruções include para fazer referência aos arquivos importados em projetos do LookML. Ele também é usado como o nome da pasta na pasta imported_projects do ambiente de desenvolvimento integrado do Looker.
  • O subparâmetro url, em que você especifica o endereço do repositório Git externo. Use o URL principal do repositório.
  • O subparâmetro ref, em que você especifica uma ramificação do Git, uma tag de versão do Git ou o SHA de uma confirmação no repositório Git. Se quiser um controle de versões estático, especifique um SHA de confirmação para que as mudanças no projeto importado não sejam refletidas automaticamente no projeto. Essa é uma boa opção para os blocos do Looker. Você também pode especificar uma ramificação ou uma tag de versão Git se quiser que o Looker detecte automaticamente novas confirmações no projeto remoto. Consulte a seção Como detectar automaticamente novas versões de um projeto remoto nesta página para saber mais.
  • O subatributo override_constant, que é um subatributo opcional que permite substituir o valor de uma constante definida em um projeto importado.

Confira um exemplo de parâmetro remote_dependency em um arquivo de manifesto de projeto. Este exemplo usa uma conexão HTTPS:

remote_dependency: ga360_block {
  url: "https://github.com/llooker/google_ga360"
  ref: "master"
  override_constant: connection {
    value: "importing_project_connection"
  }
}

Também é possível usar SSH:

remote_dependency: ga360_block {
  url: "git@github.com:llooker/google_ga360.git"
  ref: "master"
  override_constant: connection {
    value: "importing_project_connection"
  }
}

Depois de adicionar a dependência remota, talvez seja necessário configurar as credenciais de importação para o projeto remoto. Consulte a seção Como configurar as credenciais de autenticação para repositórios remotos particulares nesta página.

Como detectar automaticamente novas versões de um projeto remoto

O Looker pode detectar automaticamente novas confirmações no projeto remoto se você especificar uma ramificação do Git ou uma tag de lançamento do Git no subparâmetro ref de remote_dependency no arquivo de manifesto.

Por exemplo, esta é uma dependência remota em que a ramificação master é especificada no subparâmetro ref:

remote_dependency: exchange_rate {
  url: "https://github.com/llooker/datablocks-exchangerate.git"
  ref: "master"
}

Em seguida, quando a ramificação master for atualizada com novas confirmações, o Looker vai detectar as mudanças automaticamente.

Confira um exemplo em que a tag de lançamento v1.0 é especificada:

remote_dependency: e_faa_original {
  url: "https://github.com/llooker/google_ga360"
  ref: "v1.0"
}

Independentemente do tipo de valor especificado para o parâmetro ref, até mesmo um SHA de confirmação, o ambiente de desenvolvimento integrado vai mostrar o botão Atualizar dependências na barra de navegação superior do projeto quando você adicionar um parâmetro remote_dependency.

Clique em Update Dependencies para trazer os arquivos de projeto remoto. Se essa for a primeira dependência remota adicionada ao projeto, a atualização das dependências também vai solicitar que o Looker crie um arquivo de bloqueio de manifesto. O Looker usa o arquivo de bloqueio do manifesto para rastrear a versão dos projetos remotos.

Se você especificar uma ramificação ou tag de lançamento do Git no subparâmetro ref, o Looker vai verificar novos commits sempre que o ambiente de desenvolvimento do Looker for atualizado, o que acontece quando um desenvolvedor do Looker entra no modo de desenvolvimento, realiza uma ação do Git no ambiente de desenvolvimento ou atualiza o navegador.

Se houver novas confirmações, o Looker vai mostrar a opção Update Dependencies no painel de ações do Git do ambiente de desenvolvimento integrado.

Selecione a opção Update Dependencies para incluir os arquivos de projeto remoto mais recentes no seu projeto.

Com os arquivos mais recentes, é possível validar seu LookML para verificar se todas as referências do seu projeto funcionam com os arquivos de projeto remoto atualizados. Depois, você pode corrigir as referências inválidas e implantar as mudanças sem tempo de inatividade para os usuários.

Arquivo de bloqueio de manifesto

O Looker usa o arquivo de bloqueio de manifesto com o nome de arquivo manifest_lock.lkml para rastrear as versões dos projetos importados remotamente. O arquivo de bloqueio de manifesto aparece no painel do navegador de arquivos do Looker IDE.

Os desenvolvedores do Looker não precisam criar ou editar o arquivo de bloqueio do manifesto, porque ele é gerenciado automaticamente pelo Looker.

O arquivo de bloqueio de manifesto mostra cada projeto remoto, representado por uma entrada remote_dependency com os subparâmetros url e ref:

  • O parâmetro remote_dependency indica o nome do projeto remoto especificado por um desenvolvedor do Looker no arquivo de manifesto.
  • O subparâmetro url indica o endereço do repositório Git externo que um desenvolvedor do Looker especificou no arquivo de manifesto.
  • O subatributo ref mostra a versão do projeto (indicada por um SHA de confirmação) que o Looker está usando no projeto:
    • Se o projeto remoto foi definido no arquivo de manifesto com um ref de uma ramificação do Git ou uma tag de lançamento do Git, o parâmetro ref mostra qual versão dos arquivos (o SHA de confirmação do projeto remoto) seu projeto está usando no momento. Se houver novas confirmações no projeto remoto, o Looker vai mostrar o botão Update Dependencies no ambiente de desenvolvimento integrado para que você possa importar os arquivos mais recentes do projeto remoto. O valor ref no arquivo de bloqueio do manifesto será atualizado para mostrar o SHA de confirmação mais recente para essa ramificação ou tag de lançamento.
    • Se o projeto remoto foi definido no arquivo de manifesto com um ref de um SHA de confirmação específico, o parâmetro ref no arquivo de bloqueio de manifesto será o mesmo SHA de confirmação.

Como configurar credenciais de autenticação para repositórios remotos particulares

Para configurar credenciais de autenticação para repositórios remotos particulares, acesse a página Importar credenciais selecionando Configurações no painel de navegação esquerdo do ambiente de desenvolvimento integrado.

As configurações de Importar credenciais mostram uma lista dos URLs de cada repositório remoto que foi definido no arquivo de manifesto do projeto, o tipo de autenticação usado para o repositório (https ou ssh) e se o Looker consegue se conectar ao repositório.

Como adicionar credenciais de autenticação

Para adicionar credenciais de autenticação a um repositório:

  1. Na página Importar credenciais, no título URL, mantenha o ponteiro do mouse sobre o nome de um repositório para exibir os botões Testar e Configurar e clique em Configurar.

  2. O Looker exibe a caixa de diálogo Configure Git Authentication para permitir que você configure as credenciais do repositório remoto. A caixa de diálogo vai indicar o tipo de credenciais necessárias para esse repositório específico.

    • Se o repositório exigir um nome de usuário e uma senha (ou um token de acesso pessoal) para a autenticação, digite o nome de usuário e a senha ou o token e clique em Salvar alterações.

    • Se o repositório exigir uma chave SSH, como no exemplo de uso do SSH para importar um projeto remoto explicado anteriormente nesta página, o Looker vai mostrar uma caixa de diálogo com a chave SSH local. Clique em Copiar chave para copiar a chave SSH para a área de transferência e adicioná-la à lista de chaves do repositório.

  3. Depois de salvar as credenciais, clique em Testar para testar o acesso do Looker ao repositório.

    Depois de passar nos testes de conexão e se conectar ao repositório, a seção Importar credenciais mostrará uma marca de seleção verde ao lado do nome do repositório.

Como editar credenciais de autenticação

Para editar as credenciais de autenticação de um repositório:

  1. Para exibir os botões Testar e Editar, mantenha o ponteiro do mouse sobre um repositório que já tenha credenciais de autenticação configuradas e clique em Editar.

  2. Se o repositório exigir um nome de usuário e uma senha (ou um token de acesso pessoal) para a autenticação, clique em Limpar credenciais e, na caixa de diálogo de confirmação, clique em Sim, limpar credenciais.

  3. Digite as novas credenciais na caixa de diálogo Configure Git Authentication e clique em Save Changes.

Como visualizar arquivos de um projeto importado

O Looker IDE mostra arquivos de projetos importados na pasta imported_projects do painel de navegação à esquerda. Você pode selecionar um arquivo de projeto importado para conferir o conteúdo dele.

Arquivos de projetos locais e projetos remotos são listados na pasta imported_projects.

Também é possível acessar objetos de arquivos de projeto importados que estão incluídos no projeto ativo no navegador de objetos. Acesse o navegador de objetos na barra de navegação do Looker IDE.

Além disso, os usuários com a permissão develop podem usar o painel de metadados para conferir informações sobre objetos de projetos importados, incluindo links para navegar até o arquivo importado em que o objeto é definido. Consulte a página de documentação Metadados de objetos do LookML para mais informações.

Como incluir arquivos de um projeto importado

O parâmetro include em um arquivo de modelo especifica os arquivos de projeto que estarão disponíveis para esse modelo. Depois de especificar um projeto importado local ou remoto no arquivo de manifesto, é possível usar o parâmetro include em um arquivo de modelo para especificar arquivos do projeto importado. Somente arquivos cujo projeto está listado no arquivo de manifesto podem ser incluídos.

Para usar o comando include em um arquivo de outro projeto, use o nome do arquivo com duas barras (//) e o nome do projeto importado. Coloque uma única barra (/) no nome do projeto importado e o caminho completo do arquivo que você quer incluir.

Por exemplo, estes comandos include indicam o arquivo de visualização users do projeto importado e_flights e a visualização orders do projeto importado e_commerce:

include: "//e_flights/views/users.view.lkml"
include: "//e_commerce/public/orders.view.lkml"

Consulte a seção Sintaxe do caminho da página de parâmetro include para informações sobre como especificar caminhos com pastas do ambiente de desenvolvimento integrado ativadas.

Você pode usar caracteres curinga para incluir vários arquivos. Por exemplo, para incluir todos os arquivos de visualização no diretório /views/ do projeto importado e_flights:

include: "//e_flights/views/*.view"

Além disso, é possível usar caracteres curinga para definir níveis de diretório específicos ou diretórios recursivos no projeto importado:

include: "//e_flights/*/*.view.lkml"
include: "//e_commerce/*/*.view.lkml"

Consulte a seção Exemplos de caracteres curinga da página de parâmetros include para saber mais sobre o uso de caracteres curinga com pastas do ambiente de desenvolvimento integrado ativadas.

Como incluir arquivos de modelo

Não é possível incluir um arquivo de modelo de outro projeto. Em vez disso, se você quiser reutilizar, refinar ou extend as Análises entre projetos, no projeto importado, crie um arquivo separado e inclua esse arquivo em outros projetos. Consulte a seção Como incluir análises em um modelo da página de documentação do parâmetro include para mais informações.

Incluir arquivos que incluem outros arquivos

Quando você inclui um arquivo que inclui outros arquivos, todas as inclusões são resolvidas antes que o arquivo seja passado para o próximo projeto que o inclui.

Por exemplo, se no projeto atual você importar um arquivo (A) de outro projeto (proj_A) e o arquivo importado contiver um parâmetro include que inclui o arquivo B do projeto proj_B, o arquivo B será incluído no arquivo A antes que o arquivo A seja importado para o projeto atual.

Como importar arquivos de dados

Os arquivos armazenados na seção de dados de um projeto não são importados. Para referenciar um arquivo de dados de um projeto importado, como no parâmetro map_layer, use o caminho completo e o nome do arquivo. Exemplo:

map_layer: json_from_imported_project {
  file: "//path_to_imported_project/folder/filename.topojson"
  ...
}

Como referenciar arquivos de um projeto importado

Depois de importar um arquivo de visualização para o projeto, use a sintaxe ${view_name.field_name} para fazer referência aos campos da visualização importada, como se o arquivo fizesse parte do projeto. Por exemplo, digamos que você importou o projeto ga_360_block para o arquivo de manifesto do projeto e tem a seguinte instrução include no arquivo de modelo:

include: "//ga_360_block/ga_block.view"

Use a sintaxe ${ga_block.hits_total} para fazer referência ao campo hits_total da visualização ga_block incluída.

Como usar constantes em arquivos de um projeto importado

As constantes do LookML permitem que você defina um valor no arquivo de manifesto do projeto que pode ser reutilizado em todo o projeto. O subparâmetro export do parâmetro constant especifica se o valor de uma constante pode ser substituído quando os arquivos que fazem referência a essa constante são importados para outro projeto.

O parâmetro export tem os seguintes valores possíveis:

  • none: o valor padrão de export. Não é possível substituir o valor da constante no projeto de importação. O projeto de importação usa o valor constante especificado no arquivo de manifesto do projeto importado.
  • override_optional: o valor da constante pode ser substituído no projeto de importação. Se um valor não for fornecido no arquivo de manifesto do projeto de importação, o valor original do projeto importado será usado.
  • override_required: o projeto de importação precisa substituir o valor constante especificado originalmente no arquivo de manifesto do projeto importado. Se um novo valor constante não for fornecido no projeto de importação, o Looker vai mostrar um erro.

Ao importar arquivos que fazem referência a uma constante no projeto, é possível usar o subatributo override_constant de local_dependency ou remote_dependency no arquivo de manifesto do projeto para fornecer um novo valor para essa constante, desde que a constante tenha export definido como override_optional ou override_required no projeto original. Quando você substitui o valor de uma constante de um projeto importado, o projeto usa o valor especificado com o parâmetro override_constant.

Por exemplo, suponha que você esteja gerenciando vários bancos de dados em uma única instância do Looker, com um projeto separado para cada banco de dados. Além disso, suponha que os esquemas de dados são idênticos para cada banco de dados e que seu objetivo é definir uma análise uma vez e aplicá-la a cada conjunto de dados.

Neste exemplo, suponha que proj_core seja o projeto base em que você definiu visualizações que gostaria de importar para outros projetos. Além disso, uma das visualizações que você quer importar é a orders, definida da seguinte maneira:


view: orders {
  sql_table_name: "@{schema_name}.orders"
}

O esquema em que a visualização orders se baseia é especificado no parâmetro sql_table_name usando a constante schema_name, definida no arquivo de manifesto proj_core. No exemplo a seguir, como a constante schema_name está definida como export: override_required, qualquer projeto que importar schema_name precisará substituir o valor usando o parâmetro override_constant:


constant: schema_name {
  value: "proj_core_schema"
  export: override_required
}

Por exemplo, suponha que você queira importar a visualização orders para um projeto local chamado proj_a. Há também uma tabela chamada orders no banco de dados de proj_a com uma estrutura idêntica à tabela orders no projeto base, proj_core.

Como proj_core e proj_a estão na mesma instância, você pode importar a visualização orders para proj_a usando local_dependency. Usando o subatributo override_constant de local_dependency, é possível atualizar a constante schema_name para apontar para o esquema proj_a_schema no arquivo de manifesto de proj_a:


project_name: "proj_a"

local_dependency: {
  project: "proj_core"
  override_constant: schema_name {
    value: "proj_a_schema"
  }
}

Neste exemplo, como a constante schema_name está definida como export: override_required em project_core, o Looker vai mostrar um erro se você não substituir o valor em proj_a (o projeto de importação).

A substituição da constante schema_name em proj_a permite usar os campos definidos na visualização orders em proj_core, em vez de criar um novo arquivo de visualização e definir os campos do zero. Neste exemplo, a visualização orders corresponde a uma tabela diferente para cada projeto:

  • Em proj_core, a visualização orders é baseada na tabela proj_core_schema.orders do seu banco de dados.
  • Em proj_a, a visualização orders é baseada na tabela proj_a_schema.orders do seu banco de dados.