Como importar arquivos de outros projetos

O recurso de importação de projetos locais é um recurso experimental do Labs que importa arquivos de projetos LookML locais. Os recursos experimentais não estão totalmente desenvolvidos e podem ser completamente alterados ou completamente removidos.

No momento, a importação de arquivos de projetos LookML remotos ou locais não é compatível com a localização de modelos.

Você pode 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:

  • Construindo sobre um Looker Block instalado, sem ter que fazer alterações diretamente nele. Se o Looker fizer alterações no bloco, você poderá extraí-las facilmente, porque todos os LookML adicionados a ele serão mantidos em um repositório separado.

  • Manter um projeto base gerado automaticamente com base no esquema do banco de dados. Você pode colocar todas as suas dimensões, medidas 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 à medida que o esquema do banco de dados muda sem substituir todo o LookML personalizado.

  • Encapsular objetos compartilhados em um único projeto e depois importá-los para vários outros projetos. Por exemplo, se você tem uma tabela comum a vários bancos de dados, pode colocá-la em um projeto e mantê-la nesse local. Em seguida, faça com que vários outros projetos o utilizem importando a tabela para esses projetos.

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. Ver arquivos de um projeto importado.
  4. Incluir arquivos de um projeto importado.

Assim, você vai poder fazer referência aos campos nos arquivos do projeto importado e modificar os valores das constantes definidos no projeto importado se elas permitirem a modificação.

Como criar um arquivo de manifesto do projeto

Qualquer projeto que importa arquivos de outros projetos precisa ter um arquivo de manifesto do projeto. Se o projeto ainda não tiver um arquivo de manifesto, crie um no ícone + na parte superior do navegador de arquivos do 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

Seu administrador do Looker precisa ativar o recurso Importação de projeto local para permitir que os arquivos locais sejam importados para seu projeto.

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 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, o que significa que as alterações no projeto importado afetarão imediatamente o projeto que o importou. Isso permite que os desenvolvedores validem as alterações nos dois projetos antes de enviá-los para produção. Além disso, para desenvolvedores com permissões de modelo em ambos os projetos, os arquivos de projeto importados refletirão o status de Modo de desenvolvimento do desenvolvedor. Assim, se o desenvolvedor estiver no modo de desenvolvimento, o ambiente de desenvolvimento integrado do Looker 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 exibirá 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 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 remota do projeto em vez da importação local:

  • Seus desenvolvedores não têm permissões nos modelos do projeto importado. Quando esse é o caso, o Looker faz uma clonagem do modo de produção do projeto importado e exibe essa versão estática dos arquivos no ambiente de desenvolvimento integrado. Esta 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 remota de produtos e fornecer um ref que especifique um branch 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 exibir a versão mais recente dos arquivos do projeto remoto.
  • Seus 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 é importado pelo repositório Git remoto.

Para importar um repositório remoto, use o parâmetro remote_dependency e forneça as informações do repositório remoto. 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 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 do Git. É possível especificar um SHA de confirmação se você quiser o controle de versão estático para que as alterações no projeto importado não sejam refletidas automaticamente no projeto. Essa é uma boa opção para Looker Blocks. Também é possível especificar um branch ou uma tag de versão do Git se quiser que o Looker detecte automaticamente novos commits no projeto remoto. Consulte a seção Detectar automaticamente 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.

Veja 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 pode detectar automaticamente novas confirmações no projeto remoto se você especificar um branch 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 automaticamente as mudanças.

E este é um exemplo em que a tag de versão v1.0 é especificada:

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

Independentemente do tipo de ref especificado, até mesmo um SHA de commit, o ambiente de desenvolvimento integrado exibirá o botão Atualizar dependências quando você adicionar um parâmetro remote_dependency ao projeto:

Clique no botão para acessar os arquivos do projeto remoto. Se essa for a primeira dependência remota que você adicionou ao projeto, a atualização das dependências também solicitará que o Looker crie um arquivo de bloqueio de manifesto. O Looker usa o arquivo de bloqueio do manifesto para acompanhar a versão dos projetos remotos.

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

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

Selecione a opção Update Dependencies para trazer os arquivos mais recentes do projeto para seu projeto.

Quando tiver os arquivos mais recentes, será possível validar seu LookML para verificar se todas as referências do projeto funcionam com os arquivos atualizados do projeto remoto. Em seguida, você pode corrigir todas as referências inválidas 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 para acompanhar as versões de projetos importados remotamente:

Os desenvolvedores do Looker não precisam criar ou editar o arquivo de bloqueio do manifesto, já que eles 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 que um desenvolvedor do Looker especificou 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 um ref de uma ramificação do Git ou uma tag de versão do Git, o parâmetro ref mostrará qual versão dos arquivos (o SHA do commit remoto) está usando no momento. Se houver novas confirmações no projeto remoto, o Looker exibirá o botão Atualizar dependências no ambiente de desenvolvimento integrado para que você possa trazer os arquivos mais recentes do projeto remoto. O valor ref no arquivo de bloqueio do manifesto será atualizado para mostrar o SHA de commit mais recente para essa tag de tag ou versão.
    • 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 privados

As configurações de Importar credenciais mostram uma lista dos URLs para 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 pode se conectar ao repositório.

Como adicionar credenciais de autenticação

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

  1. 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 exibe uma caixa de diálogo que permite configurar credenciais para o repositório remoto. A caixa de diálogo indicará o tipo de credencial necessária para esse repositório específico.

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

      O Looker não é compatível com tokens de acesso pessoais refinados do GitHub. Para conectar seu projeto do Looker ao GitHub usando HTTPS, use a opção Tokens (clássico) do GitHub ao criar um token de acesso pessoal.

    • Se o repositório exigir uma chave SSH, como neste exemplo acima, o Looker exibirá uma caixa de diálogo mostrando sua 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.

      Se o projeto remoto for um repositório LookML, as chaves SSH talvez já existam. Por exemplo, uma chave SSH provavelmente foi adicionada ao repositório quando o projeto LookML foi originalmente conectado ao Git. Deixe todas as chaves SSH existentes ao adicionar sua nova chave SSH ao repositório.

  3. Depois de salvar as credenciais, clique no botão Test 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 mostra 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. Passe o cursor sobre um repositório que já tem credenciais de autenticação configuradas para exibir os botões Testar e Editar e clique em Editar:

  2. Se o repositório exigir um nome de usuário e uma 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 Configure Git Authentication e clique em Save Changes.

Como visualizar arquivos de um projeto importado

O ambiente de desenvolvimento integrado do Looker exibe arquivos de projetos importados na pasta imported_projects do painel de navegação à esquerda. Clique em um arquivo de projeto importado para ver o conteúdo dele:

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

Como eles não podem ser editados, os arquivos de projetos importados não ficam visíveis quando você está editando arquivos em massa no ambiente de desenvolvimento integrado.

Também é possível ver 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 ambiente de desenvolvimento integrado do Looker:

Além disso, os usuários com 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. Consulte a página de documentação Metadados para objetos LookML e veja 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, use o parâmetro include em um arquivo de modelo para especificar arquivos do projeto importado. Somente arquivos cujo projeto esteja listado no arquivo de manifesto podem ser incluídos.

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 de documentação Como trabalhar com pastas no ambiente de desenvolvimento integrado para mais 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 o 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 de documentação Como trabalhar com pastas no ambiente de desenvolvimento integrado para ver informações sobre como usar 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 estender o recurso Explorar em projetos, é possível criar um arquivo Explorar separado no projeto importado e incluir esse arquivo em outros projetos. Consulte a seção Como incluir explorações em um modelo da página de documentação do parâmetro include para mais informações.

Incluir arquivos com outros arquivos

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

Por exemplo, se 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 do arquivo A ser importado para o projeto atual.

Como importar 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 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 referenciar os campos da visualização importada como se o arquivo de visualização fosse nativo para esse projeto. Por exemplo, digamos que você tenha importado 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"

Use a sintaxe ${ga_block.hits_total} para referenciar o campo hits_total na visualização ga_block incluída.

Como usar constantes em arquivos de um projeto importado

As constantes de LookML permitem que você defina um valor no arquivo de manifesto do seu 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 modificado 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 para 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 modificado no projeto de importação. Se não for fornecido um valor no arquivo de manifesto do projeto importado, será usado o valor original do projeto importado.
  • override_required: o projeto de importação precisa modificar 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 exibirá um erro.

Ao importar arquivos que fazem referência a uma constante no seu projeto, você pode usar o subparâmetro override_constant de local_dependency ou remote_dependency no arquivo de manifesto do seu projeto para fornecer um novo valor para essa constante, desde que essa 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, seu projeto usa o valor especificado com o parâmetro override_constant.

Constantes estão disponíveis apenas para arquivos do projeto no qual elas foram originalmente definidas. Portanto, as constantes definidas em um projeto cujos arquivos você importou só podem ser usados pelos arquivos importados, e não pelos arquivos definidos no projeto de importação.

Se você quiser usar uma constante nos arquivos do projeto de importação, use o parâmetro constant para definir uma nova constante no arquivo de manifesto do projeto. Uma constante definida dessa maneira estará disponível somente para os arquivos definidos no projeto de importação.

Por exemplo, digamos que você esteja gerenciando vários bancos de dados em uma única instância do Looker, com um projeto separado para cada um deles. Neste exemplo, vamos supor que os esquemas de dados são idênticos para cada banco de dados e que sua meta é 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 as visualizações que quer importar para outros projetos. Além disso, uma das visualizações que você quer importar é a visualização 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 abaixo, como a constante schema_name está definida como export: override_required, qualquer projeto que importe schema_name precisa modificar 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 proj_a usando local_dependency. Usando o subparâmetro override_constant de local_dependency, você pode 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 exibirá um erro se você não modificar o valor em proj_a (o projeto de importação).

Modificar a 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 no banco de dados.
  • Em proj_a, a visualização orders é baseada na tabela proj_a_schema.orders no banco de dados.