Importar ficheiros de outros projetos

Pode importar ficheiros de outros projetos do LookML e repositórios externos para o seu projeto atual, o que lhe permite usar ficheiros de modelos, ficheiros de visualização e outros ficheiros em mais do que um projeto. Os projetos importados são apenas de leitura. Se quiser editar os ficheiros, tem de os editar a partir do respetivo projeto do LookML (ou de outro editor ligado ao repositório Git dos ficheiros).

Existem vários exemplos de utilização para importar ficheiros para o seu projeto LookML. Seguem-se alguns exemplos:

• Criar com base num Looker Block instalado sem ter de fazer alterações diretas ao mesmo. Se o Looker fizer alterações ao bloco, pode incorporar as alterações, uma vez que todo o LookML que adicionou ao mesmo é mantido num repositório separado.

• Manter um projeto base gerado automaticamente com base no esquema da base de dados. Pode colocar todas as dimensões personalizadas, medidas e semelhantes num projeto separado que importe todo o LookML do projeto gerado automaticamente. Pode regenerar regularmente o projeto base à medida que o esquema da base de dados muda, sem substituir todo o seu LookML personalizado.

• Encapsular objetos partilhados num único projeto e, em seguida, importá-los para vários outros projetos. Por exemplo, se tiver uma tabela comum a várias bases de dados, pode colocar a vista correspondente num projeto e mantê-la nesse local. Em seguida, faça com que vários outros projetos a usem importando a tabela para esses projetos.

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

1. Crie um ficheiro de manifesto do projeto.
2. Especifique os projetos locais ou remotos que quer importar.
3. Ver ficheiros de um projeto importado.
4. Inclua ficheiros de um projeto importado.

Em seguida, pode fazer referência a campos dos ficheiros do projeto importado e substituir os valores das constantes definidas no projeto importado, se as constantes permitirem a substituição.

Criar um ficheiro de manifesto do projeto

Qualquer projeto que importe ficheiros de outros projetos tem de ter um ficheiro de manifesto do projeto. Se o seu projeto ainda não tiver um ficheiro de manifesto, pode criar um a partir do ícone + na parte superior do explorador de ficheiros no IDE do Looker.

Para importar projetos, especifique-os no manifesto. Pode especificar projetos locais ou remotos, conforme descrito nas secções seguintes.

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 programadores tenham autorizações de modelo para os modelos do projeto importado. Se os seus programadores tiverem autorizações de modelo no projeto importado, o controlo de versões é dinâmico, o que significa que as alterações no projeto importado afetam imediatamente o projeto que o importa. Isto permite que os programadores validem as alterações em ambos os projetos antes de as enviarem para produção. Além disso, para os programadores com autorizações de modelos em ambos os projetos, os ficheiros de projetos importados refletem o estado do modo de programação do programador. Assim, se o programador estiver no modo de desenvolvimento, o IDE do Looker mostra o modo de desenvolvimento dos ficheiros do projeto importado. Se o programador estiver no modo de produção, o IDE do Looker apresenta o modo de produção do projeto importado.

No ficheiro de manifesto, o parâmetro project_name especifica o nome do projeto atual (o Looker preenche automaticamente este parâmetro quando cria o ficheiro de manifesto para o projeto). Para importar um projeto local para o projeto atual, use um ou mais parâmetros local_dependency para especificar o projeto ou os projetos a importar:

# This project
project_name: "my_project"

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

Nos seguintes cenários, deve usar a importação de projetos remotos em vez da importação de projetos locais:

• Os seus programadores não têm autorizações de modelo nos modelos do projeto importado. Quando é este o caso, o Looker cria um clone do modo de produção do projeto importado e apresenta essa versão estática dos ficheiros no IDE. Esta versão estática nunca mostra a versão do modo de desenvolvimento dos ficheiros e também pode estar desatualizada em relação ao modo de produção atual sem alertar o programador. É melhor usar a importação de projetos remotos e fornecer um ref que especifique um ramo Git ou um lançamento Git no projeto remoto. Se o fizer, o Looker deteta automaticamente novos commits no projeto remoto, para que os programadores sejam alertados e possam, em seguida, importar a versão mais recente dos ficheiros do projeto remoto.
• Os programadores têm de trabalhar sempre com a versão de produção de um projeto importado.
• Os seus programadores têm de trabalhar com uma versão estática dos ficheiros do projeto importado.

Importar projetos remotos

Numa importação remota, o projeto importado não tem de estar na mesma instância. Em vez disso, o projeto é importado através do respetivo repositório Git remoto.

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

• O nome do projeto importado, que pode ser qualquer nome à sua escolha. No exemplo seguinte, o nome do projeto é ga_360_block. Usa este nome em declarações include para fazer referência aos ficheiros importados em projetos LookML. O nome também é usado como o nome da pasta na pasta imported_projects do IDE do Looker.
• O subparâmetro url, onde especifica o endereço do repositório Git externo. Use o URL principal do repositório.
• O subparâmetro ref, onde especifica um ramo do Git, uma etiqueta de lançamento do Git ou o SHA de uma confirmação no repositório do Git. Pode especificar um SHA de commit se quiser uma gestão de versões estática, para que as alterações no projeto importado não se reflitam automaticamente no seu projeto (esta é uma boa opção para blocos do Looker). Em alternativa, pode especificar um ramo Git ou uma etiqueta de lançamento Git se quiser que o Looker detete automaticamente novos commits no projeto remoto. Consulte a secção Deteção automática de novas versões de um projeto remoto nesta página para mais informações.
• O subparâmetro override_constant, que é um subparâmetro opcional que lhe permite substituir o valor de uma constante definida num projeto importado.

Segue-se um exemplo de um parâmetro remote_dependency num ficheiro de manifesto do projeto. Este exemplo usa uma ligação HTTPS:

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

Também pode usar SSH:

remote_dependency: ga360_block {
  url: "[email protected]:llooker/google_ga360.git"
  ref: "master"
  override_constant: connection {
    value: "importing_project_connection"
  }
}

Depois de adicionar a dependência remota, pode ter de configurar as credenciais de importação para o projeto remoto. Consulte a secção Configurar credenciais de autenticação para repositórios remotos privados nesta página.

Detetar automaticamente novas versões de um projeto remoto

Pode fazer com que o Looker detete automaticamente novas confirmações no projeto remoto se especificar um ramo do Git ou uma etiqueta de lançamento do Git no subparâmetro ref de remote_dependency no ficheiro de manifesto.

Por exemplo, aqui está 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"
}

Posteriormente, quando a ramificação master é atualizada com novos commits, o Looker deteta automaticamente as alterações.

Segue-se um exemplo em que a etiqueta 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 que especificar para o parâmetro ref, mesmo um SHA de commit, o IDE apresenta o botão Atualizar dependências na barra de navegação do projeto superior quando adiciona um parâmetro remote_dependency ao seu projeto.

Clique em Atualizar dependências para importar os ficheiros do projeto remoto. Se esta for a primeira dependência remota que adicionou ao seu projeto, a atualização das dependências também pede ao Looker para criar um ficheiro de bloqueio do manifesto. O Looker usa o ficheiro de bloqueio do manifesto para acompanhar a versão dos projetos remotos.

Se especificar um ramo Git ou uma etiqueta de lançamento Git no subparâmetro ref, o Looker verifica se existem novas confirmações sempre que o IDE do Looker é atualizado, o que acontece quando um programador do Looker entra no modo de desenvolvimento, executa uma ação Git no IDE ou atualiza o navegador.

Se existirem novas confirmações, o Looker apresenta a opção Atualizar dependências no painel de ações do Git do IDE.

Selecione a opção Atualizar dependências para importar os ficheiros do projeto remoto mais recentes para o seu projeto.

Depois de ter os ficheiros mais recentes, pode validar o LookML para verificar se todas as referências do seu projeto funcionam com os ficheiros do projeto remoto atualizados. Em seguida, pode corrigir quaisquer referências danificadas e implementar as alterações sem tempo de inatividade para os utilizadores.

Ficheiro de bloqueio do manifesto

O Looker usa o ficheiro de bloqueio do manifesto com o nome de ficheiro manifest_lock.lkml para acompanhar as versões de projetos importados remotamente. O ficheiro de bloqueio do manifesto é apresentado no painel do explorador de ficheiros do IDE do Looker.

Os programadores do Looker não precisam de criar nem editar o ficheiro de bloqueio do manifesto, uma vez que os ficheiros de bloqueio são geridos automaticamente pelo Looker.

O ficheiro 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 programador do Looker especificou no ficheiro de manifesto.
• O subparâmetro url indica o endereço do repositório Git externo que um programador do Looker especificou no ficheiro de manifesto.
• O subparâmetro ref mostra a versão do projeto (indicada por um SHA de commit) que o Looker está a usar no seu projeto:
  • Se o projeto remoto tiver sido definido no ficheiro de manifesto com um ref de um ramo do Git ou uma etiqueta de lançamento do Git, o parâmetro ref mostra que versão dos ficheiros (o SHA de confirmação do projeto remoto) o seu projeto está a usar atualmente. Se existirem novas consolidações no projeto remoto, o Looker apresenta o botão Atualizar dependências no IDE para que possa importar os ficheiros do projeto remoto mais recentes. O valor ref no ficheiro de bloqueio do manifesto é atualizado para mostrar o SHA de confirmação mais recente para essa ramificação ou etiqueta de lançamento.
  • Se o projeto remoto tiver sido definido no ficheiro de manifesto com um ref de um SHA de commit específico, o parâmetro ref no ficheiro de bloqueio do manifesto será o mesmo SHA de commit.

Configurar credenciais de autenticação para repositórios remotos privados

Para configurar credenciais de autenticação para repositórios remotos privados, navegue para a página Importar credenciais selecionando Definições tune no painel de navegação do lado esquerdo no IDE.

As definições de Import Credentials (Importar credenciais) mostram uma lista dos URLs de cada repositório remoto que foi definido no ficheiro de manifesto do projeto, o tipo de autenticação usado para o repositório (https ou ssh) e se o Looker consegue estabelecer ligação com êxito ao repositório.

Adicionar credenciais de autenticação

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

1. Na página Importar credenciais, no cabeçalho URL, mantenha o ponteiro sobre o nome de um repositório para apresentar os botões Testar e Configurar e clique em Configurar.

   

2. O Looker apresenta a caixa de diálogo Configurar autenticação Git para lhe permitir configurar credenciais para o repositório remoto. A caixa de diálogo indica o tipo de credenciais necessárias para esse repositório específico.

   • Se o repositório exigir um nome de utilizador e uma palavra-passe (ou um token de acesso pessoal) para autenticação, introduza o seu nome de utilizador e palavra-passe ou token e clique em Guardar alterações.

   • Se o repositório exigir uma chave SSH, como no exemplo de utilização de SSH para importar um projeto remoto explicado anteriormente nesta página, o Looker apresenta uma caixa de diálogo que mostra a 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.

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

   

   Depois de passar nos testes de ligação e estabelecer ligação ao repositório, a secção Importar credenciais mostra uma marca de verificação verde junto ao nome do repositório.

Editar credenciais de autenticação

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

1. Para apresentar os botões Testar e Editar, mantenha o ponteiro 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 utilizador e uma palavra-passe (ou um token de acesso pessoal) para autenticação, clique em Limpar credenciais e, na caixa de diálogo de confirmação, clique em Sim, limpar credenciais.

3. Introduza as novas credenciais na caixa de diálogo Configurar autenticação Git e clique em Guardar alterações.

Visualizar ficheiros de um projeto importado

O IDE do Looker apresenta os ficheiros do projeto importados na pasta imported_projects do painel de navegação do lado esquerdo. Pode selecionar um ficheiro de projeto importado para ver o respetivo conteúdo.

Os ficheiros de projetos locais e projetos remotos são apresentados na pasta imported_projects.

Também pode ver objetos de ficheiros de projetos importados que estão incluídos no projeto ativo a partir do explorador de objetos. Aceda ao navegador de objetos a partir da barra de navegação do IDE do Looker.

Além disso, os utilizadores com a autorização develop podem usar o painel de metadados para ver informações sobre objetos de projetos importados, incluindo links para navegar para o ficheiro importado onde o objeto está definido. Consulte a página de documentação Metadados para objetos LookML para mais informações.

Incluindo ficheiros de um projeto importado

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

Para include um ficheiro de outro projeto, use o nome do ficheiro com duas barras (//) e o nome do projeto importado. Faça seguir o nome do projeto importado com uma barra (/) e o caminho completo para o ficheiro que quer incluir.

Por exemplo, estes comandos include indicam o ficheiro 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 secção Sintaxe do caminho da página de parâmetros include para obter informações sobre como especificar caminhos com pastas do IDE ativadas.

Pode usar carateres universais para incluir vários ficheiros. Por exemplo, para incluir todos os ficheiros de visualização no diretório /views/ do projeto importado e_flights:

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

Além disso, pode usar carateres universais para definir o âmbito de níveis de diretórios específicos ou de diretórios recursivos no projeto importado:

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

Consulte a secção Exemplos de carateres universais da página de parâmetros include para obter informações sobre a utilização de carateres universais com as pastas do IDE ativadas.

Incluindo ficheiros de modelos

Não pode incluir um ficheiro de modelo de outro projeto. Em alternativa, se quiser reutilizar, refinar ou estender as análises detalhadas em vários projetos, no projeto importado, pode criar um ficheiro de análise detalhada separado e, em seguida, incluir esse ficheiro de análise detalhada noutros projetos. Consulte a secção Incluir explorações num modelo da página de documentação de parâmetros include para mais informações.

Incluindo ficheiros que incluem outros ficheiros

Quando inclui um ficheiro que inclui outros ficheiros, todas as inclusões são resolvidas antes de o ficheiro ser transmitido ao projeto seguinte que o inclui.

Por exemplo, se no seu projeto atual importar um ficheiro (A) de outro projeto (proj_A) e o ficheiro importado contiver um parâmetro include que inclua o ficheiro B do projeto proj_B, o ficheiro B é incluído no ficheiro A antes de o ficheiro A ser importado para o projeto atual.

Importar ficheiros de dados

Os ficheiros armazenados na secção de dados de um projeto não são importados. Para fazer referência a um ficheiro de dados de um projeto importado, como no parâmetro map_layer, use o caminho completo e o nome do ficheiro. Por exemplo:

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

Referenciar ficheiros de um projeto importado

Depois de importar um ficheiro de visualização para o seu projeto, pode usar a sintaxe ${view_name.field_name} para fazer referência aos campos da visualização importada como se o ficheiro de visualização fizesse parte desse projeto. Por exemplo, suponhamos que importou o projeto ga_360_block no ficheiro de manifesto do projeto e tem a seguinte declaração include no ficheiro do modelo:

include: "//ga_360_block/ga_block.view"

Usaria a sintaxe ${ga_block.hits_total} para fazer referência ao campo hits_total da vista ga_block incluída.

Usar constantes em ficheiros de um projeto importado

As constantes do LookML permitem-lhe definir um valor no ficheiro 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 substituído quando os ficheiros que referenciam essa constante são importados para outro projeto.

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

• none: o valor predefinido para 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 ficheiro de manifesto do projeto importado.
• override_optional: o valor da constante pode ser substituído opcionalmente no seu projeto de importação. Se não for fornecido um valor no ficheiro de manifesto do projeto de importação, é usado o valor original do projeto importado.
• override_required: o projeto de importação tem de substituir o valor constante originalmente especificado no ficheiro de manifesto do projeto importado. Se não for fornecido um novo valor constante no projeto de importação, o Looker apresenta um erro.

Quando importa ficheiros que referenciam uma constante para o seu projeto, pode usar o subparâmetro override_constant de local_dependency ou remote_dependency no ficheiro 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 respetivo projeto original. Quando substitui o valor de uma constante de um projeto importado, o seu projeto usa o valor especificado com o parâmetro override_constant.

Por exemplo, suponha que está a gerir várias bases de dados numa única instância do Looker, com um projeto separado para cada base de dados. Suponha também que os esquemas de dados são idênticos para cada base de dados e que o seu objetivo é definir uma análise uma vez e aplicá-la a cada conjunto de dados.

Neste exemplo, suponhamos que proj_core é o projeto base no qual definiu vistas que quer importar para outros projetos. Além disso, uma das visualizações que quer importar é a visualização orders, que é definida da seguinte forma:

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

O esquema no qual a vista orders se baseia é especificado no parâmetrosql_table_name através da constante schema_name, que é definida no ficheiro de manifesto proj_core. No exemplo seguinte, uma vez que a constante schema_name está definida como export: override_required, qualquer projeto que importe schema_name tem de substituir o respetivo valor através do parâmetro override_constant:

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

Por exemplo, suponha que quer importar a vista orders para um projeto local denominado proj_a. Também existe uma tabela denominada orders na base de dados para proj_a com uma estrutura idêntica à da tabela orders no projeto base, proj_core.

Uma vez que proj_core e proj_a estão na mesma instância, pode importar a vista orders para proj_a através da local_dependency. Em seguida, usando o subparâmetro override_constant de local_dependency, pode atualizar a constante schema_name para apontar para o esquema proj_a_schema no ficheiro de manifesto de proj_a:

project_name: "proj_a"

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

Neste exemplo, uma vez que a constante schema_name está definida como export: override_required em project_core, o Looker apresenta um erro se não substituir o respetivo valor em proj_a (o projeto de importação).

A substituição da constante schema_name em proj_a permite-lhe usar os campos que definiu na vista orders em proj_core, em vez de criar um novo ficheiro de vista e definir os campos de raiz. Neste exemplo, a vista orders corresponde a uma tabela diferente para cada projeto:

• No proj_core, a vista orders baseia-se na tabela proj_core_schema.orders na sua base de dados.
• No proj_a, a vista orders baseia-se na tabela proj_a_schema.orders na sua base de dados.