Como importar arquivos de outros projetos

É possível importar arquivos de outros projetos LookML e repositórios externos para o projeto atual. Isso permite usar arquivos de modelo, visualizar arquivos e outros arquivos em mais de um projeto.

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

  • Criar com base em um bloco do Looker instalado sem precisar fazer mudanças diretas nele. Se o Looker fizer alterações no bloco, será possível extraí-las facilmente, porque todo o LookML que você adicionou será mantido em um repositório separado.

  • Manter um projeto base que é gerado automaticamente com base no esquema do banco de dados. Coloque todas as dimensões e medidas personalizadas e assim por diante em um projeto separado que importa todo o LookML do projeto gerado automaticamente. É possível gerar novamente o projeto base regularmente conforme o esquema do banco de dados muda, sem substituir todo o LookML personalizado.

  • Encapsular objetos compartilhados em um único projeto e importá-los para vários outros projetos. Por exemplo, se você tem uma tabela comum a vários bancos de dados, pode colocar a visualização dela em um projeto e mantê-la nesse só lugar. Em seguida, faça com que vários outros projetos a usem, importando a tabela para eles.

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

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

Em seguida, você poderá fazer referência a campos nos arquivos do projeto importado e substituir os valores das constantes definidos no projeto importado, se as constantes allow override.

Como criar um arquivo de manifesto de projeto

Qualquer projeto que importa arquivos de outros projetos precisa ter um arquivo de manifesto. Se o projeto ainda não tiver um arquivo de manifesto, crie um no í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ó poderá ser usada se o projeto importado estiver presente na mesma instância do Looker. Também é recomendável que os desenvolvedores tenham permissões de modelo nos modelos do projeto importado. Se os desenvolvedores tiverem permissões de modelo no projeto importado, o controle de versões será dinâmico, o que significa que as alterações no projeto importado vão afetar imediatamente o projeto que o importar. Assim, os desenvolvedores podem validar as mudanças nos dois projetos antes de enviar para produção. Além disso, para desenvolvedores com permissões de modelo em ambos os projetos, os arquivos importados de projeto 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 esse modo 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.

Para importar localmente, use o parâmetro project_name para especificar o projeto atual. Use um ou mais parâmetros local_dependency para especificar os projetos que serão 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 faz um clone do modo de produção do projeto importado e mostra a 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 com o Modo de produção atual sem alertar o desenvolvedor. É 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 seus desenvolvedores sejam alertados e possam usar a versão mais recente dos arquivos do projeto remoto.
  • Os desenvolvedores precisam sempre trabalhar com a versão de produção de um projeto importado.
  • Seus desenvolvedores precisam trabalhar com uma versão estática dos arquivos do projeto importado.

Como importar projetos remotos

Em uma importação remota, o projeto importado não precisa estar na mesma instância. Em vez disso, o projeto será importado por meio do repositório Git remoto.

Para importar um repositório remoto, use o parâmetro remote_dependency para fornecer as informações a ele. O parâmetro remote_dependency recebe as informações e subparâmetros a seguir:

  • Nome do projeto importado, que pode ser o que você quiser. No exemplo abaixo, o nome do projeto é ga_360_block. Esse nome é usado nas instruções include para fazer referência aos arquivos importados em projetos do LookML. O nome 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 lançamento do Git ou o SHA de uma confirmação no repositório Git. Especifique um SHA de confirmação se quiser um controle de versões estático, para que as mudanças no projeto importado não sejam refletidas automaticamente no projeto. Essa é uma boa opção para Blocos do Looker. Também é possível especificar uma ramificação ou uma tag de lançamento do Git se quiser que o Looker detecte automaticamente novas confirmações no projeto remoto. Consulte a seção Detecção automática de novas versões de um projeto remoto nesta página para mais informações.
  • O subparâmetro override_constant, que é opcional e 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 do 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 credenciais de autenticação para repositórios remotos privados nesta página.

Como detectar automaticamente novas versões de um projeto remoto

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

Por exemplo, veja 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 detectará automaticamente as mudanças.

E aqui está 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, mesmo um SHA de confirmação, o ambiente de desenvolvimento integrado exibirá o botão Update Dependencies na barra de navegação superior quando você adicionar um parâmetro remote_dependency a ele.

Clique em Update Dependencies para acessar os arquivos do projeto remoto. Se esta 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 de manifesto para rastrear a versão dos projetos remotos.

Se você especificar uma ramificação ou uma tag de lançamento do Git no subparâmetro ref, o Looker vai verificar se há novas confirmações sempre que o ambiente de desenvolvimento integrado do Looker for atualizado. Isso acontece quando um desenvolvedor do Looker entra no modo de desenvolvimento, realiza uma ação do Git no ambiente de desenvolvimento integrado ou atualiza o navegador.

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

Selecione a opção Atualizar dependências para trazer os arquivos de projetos remotos mais recentes para seu projeto.

Depois de ter os arquivos mais recentes, é possível validar o LookML para verificar se todas as referências do projeto funcionam com os arquivos atualizados do projeto remoto. Assim, é possível corrigir as referências corrompidas e implantar as alterações sem inatividade para os usuários.

Arquivo de bloqueio do manifesto

O Looker usa o arquivo de bloqueio de manifesto com o nome manifest_lock.lkml para rastrear as versões de projetos importados remotos. O arquivo de bloqueio do manifesto aparece no painel do navegador de arquivos no ambiente de desenvolvimento integrado do Looker.

Os desenvolvedores do Looker não precisam criar ou editar o arquivo de bloqueio de manifesto, já que esses arquivos são gerenciados automaticamente pelo Looker.

O arquivo de bloqueio do 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 que um desenvolvedor do Looker especificou no arquivo de manifesto.
  • O subparâmetro url indica o endereço do repositório Git externo especificado por um desenvolvedor do Looker no arquivo de manifesto.
  • O subparâmetro 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 tiver sido definido no arquivo de manifesto com o ref de uma ramificação do Git ou uma tag de lançamento do Git, o parâmetro ref vai mostrar 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 Atualizar dependências no ambiente de desenvolvimento integrado para que você possa trazer os arquivos do projeto remoto mais recentes. O valor ref no arquivo de bloqueio do manifesto será atualizado para mostrar o SHA de confirmação mais recente da ramificação ou da tag de lançamento.
    • Se o projeto remoto tiver sido 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 à esquerda no ambiente de desenvolvimento integrado.

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

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, passe o cursor sobre o nome de um repositório para exibir os botões Testar e Configurar e clique em Configurar.

  2. O Looker mostra a caixa de diálogo Configurar autenticação do Git para permitir a configuração de credenciais para o repositório remoto. A caixa de diálogo indicará o tipo de credenciais necessárias para o repositório em questão.

    • Se o repositório exigir um nome de usuário e uma senha (ou um token de acesso pessoal) para a autenticação, digite seu 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 como usar SSH para importar um projeto remoto explicado anteriormente nesta página, o Looker vai mostrar uma caixa de diálogo com sua chave SSH local. Clique em Copy Key para copiar a chave SSH para a área de transferência e adicioná-la à lista de chaves do seu 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 Import Credentials 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, passe o cursor sobre um repositório que já tenha configurado credenciais de autenticação e clique em Editar.

  2. Se o repositório exigir nome de usuário e senha (ou token de acesso pessoal) para autenticação, clique em Limpar credenciais e, no pop-up de confirmação, clique em Sim, limpar credenciais.

  3. Digite as novas credenciais no pop-up Configurar autenticação do Git e clique em Salvar alterações.

Como visualizar arquivos de um projeto importado

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

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

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

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

Como incluir arquivos de um projeto importado

O parâmetro include em um arquivo de modelo especifica os arquivos do projeto que estarão disponíveis para esse modelo. Depois de especificar um projeto importado local ou remoto no arquivo de manifesto, use o parâmetro include em um arquivo de modelo para especificar arquivos do projeto importado. Só é possível incluir arquivos cujo projeto esteja listado no arquivo de manifesto.

Para usar include em um arquivo de outro projeto, use o nome do arquivo com duas barras (//) e o nome do projeto importado. Siga o nome do projeto importado com uma única barra (/) 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 do parâmetro include para saber 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 no escopo para níveis de diretório específicos ou para 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 do parâmetro include para informações 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 modelo de outro projeto. Em vez disso, se você quiser reutilizar, refinar ou ampliar as Análises detalhadas entre projetos, no projeto importado, será possível criar um arquivo do Explore separado e incluí-lo em outros projetos. Para mais informações, consulte a seção Como incluir Análises em um modelo da página de documentação do parâmetro include.

Como incluir arquivos que incluem outros arquivos

Quando você inclui um arquivo com outros arquivos, todas essas inclusões são resolvidas antes de o arquivo ser 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 ele tiver um parâmetro include que inclua o arquivo B do projeto proj_B, o arquivo B será incluído no A antes que o A seja importado para o projeto atual.

Importação de arquivos de dados

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

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

Como fazer referência a arquivos de um projeto importado

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

include: "//ga_360_block/ga_block.view"

Você usaria 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 definir 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 estes valores possíveis:

  • none: o valor padrão de export. O valor da constante não pode ser substituído no projeto de importação. O projeto importado 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 importado, o valor original do projeto importado será usado.
  • override_required: o projeto importado 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 se referem a uma constante no projeto, você pode usar o subparâmetro override_constant de local_dependency ou remote_dependency no arquivo de manifesto do projeto para fornecer um novo valor para essa constante, desde que ela tenha export definida como override_optional ou override_required no projeto original. Quando você substituir o valor de uma constante de um projeto importado, seu projeto vai usar 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 um. Neste exemplo, também vamos supor 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 em 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, que é definida no arquivo de manifesto proj_core. No exemplo abaixo, como a constante schema_name está definida como export: override_required, qualquer projeto que importe schema_name precisa substituir o valor usando o parâmetro override_constant:


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

Neste exemplo, vamos supor 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 para 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, é possível importar a visualização orders para o proj_a usando local_dependency. Usando o subparâmetro override_constant de local_dependency, você pode atualizar a constante schema_name de modo que aponte 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 no 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 no 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:

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