Importar arquivos de outros projetos

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

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

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

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

  • Criar com base em um Looker Block instalado sem precisar fazer mudanças diretas nele. Se o Looker fizer mudanças no bloco, será possível extrair as alterações facilmente porque todo o LookML que você adicionou a ele é mantido 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 personalizadas, medidas e assim por diante, em um projeto separado que importe 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ê tiver uma tabela comum a vários bancos de dados, será possível colocá-la em um projeto e mantê-la em um só lugar. Depois faça com que vários outros projetos o usem importando a tabela para eles.

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.

Em seguida, você poderá fazer referência aos campos dos arquivos de projeto importados e modificar os valores das constantes definidos no projeto importado se as constantes permitirem a modificação.

Como criar um arquivo de manifesto do projeto

Todo projeto que importa arquivos de outros projetos precisa ter um arquivo de manifesto do projeto. Caso seu projeto ainda não tenha um arquivo de manifesto, crie um usando o í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 Importar projetos locais para permitir que arquivos locais sejam importados para seu projeto.

A importação de projetos local 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 importados. Se os desenvolvedores tiverem permissões de modelo no projeto importado, o controle de versão será dinâmico, o que significa que as mudanças no projeto importado afetarão imediatamente o projeto que o importa. Isso permite que os desenvolvedores validem as alterações nos dois projetos antes de enviarem para a produção. Além disso, para desenvolvedores com permissões de modelo nos dois projetos, os arquivos de projeto importados refletem o status de Modo de desenvolvimento do desenvolvedor. Portanto, 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 de projeto remoto em vez da importação local:

  • Seus desenvolvedores não têm permissões de modelo nos modelos do projeto importado. Quando isso acontece, o Looker faz uma cópia do 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 mostra a versão do modo de desenvolvimento dos arquivos e pode também estar desatualizada com o modo de produção atual sem alertar o desenvolvedor. Seria melhor usar a importação remota de produtos e fornecer um ref que especifique uma ramificação do Git 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.
  • Os desenvolvedores sempre precisam trabalhar 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 para fornecer 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. Esse nome é usado em instruções include para fazer referência aos arquivos importados em projetos LookML. Ele também é usado como nome da pasta imported_projects no 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. Você pode especificar um SHA de confirmação se quiser um 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. Se preferir, especifique uma ramificação do Git ou uma tag de versão do Git se quiser que o Looker detecte automaticamente novas confirmações 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 é um subparâmetro opcional que permite substituir o valor de uma constante definida em um projeto importado.

Veja um exemplo de um 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 particulares nesta página.

Detecção automática de novas versões de um projeto remoto

O Looker pode detectar automaticamente novas confirmações no projeto remoto se você especificar uma ramificação ou uma tag de versão do Git no subparâmetro ref de remote_dependency no arquivo 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"
}

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

Veja 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 que você especificar, mesmo um SHA de confirmação, o ambiente de desenvolvimento integrado exibirá o botão Atualizar dependências quando você adicionar um parâmetro remote_dependency ao seu projeto:

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

Se você especificar uma ramificação do Git ou uma tag de versão 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 ambiente de desenvolvimento integrado do Git:

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

Quando você tiver os arquivos mais recentes, poderá validar o LookML para verificar se todas as referências do projeto funcionam com os arquivos de projeto remoto atualizados. Em seguida, corrija as referências corrompidas e implante as alterações sem inatividade para os usuários.

Arquivo de bloqueio do manifesto

O Looker usa o arquivo de bloqueio de manifesto para rastrear 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 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 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 (indicado por um SHA de confirmação) que o Looker está usando no seu projeto:
    • Se o projeto remoto tiver sido definido no arquivo de manifesto com uma 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 projeto remoto) o projeto 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 confirmação mais recente para essa ramificação ou 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 do manifesto será o mesmo SHA de confirmação.

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

As configurações de Import Credentials mostram uma lista dos URLs para cada repositório remoto 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.

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 vai 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 a autenticação, digite seu nome de usuário e senha ou token e clique em Salvar alterações.

    • Se o repositório exigir uma chave SSH, como neste exemplo acima, o Looker exibirá uma caixa de diálogo que mostra 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, talvez já exista chaves SSH, como uma chave SSH que foi adicionada ao repositório quando o projeto LookML foi originalmente conectado ao Git. Deixe as chaves SSH atuais em vigor ao adicionar sua nova chave SSH ao repositório.

  3. Depois de salvar as credenciais, clique no botão 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 vai mostrar uma marca de seleção verde ao lado do nome do repositório.

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á configurou as credenciais de autenticação para mostrar 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 a autenticação, clique em Limpar credenciais e, no pop-up de confirmação, clique em Sim, limpar as credenciais.

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

Visualizar arquivos de um projeto importado

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

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

Como eles não podem ser editados, os arquivos de projeto importados não ficam visíveis quando você edita 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 pelo 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 para saber mais.

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 o 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 com projetos listados 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 para o 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 de caminho da página de documentação Como trabalhar com pastas no ambiente de desenvolvimento integrado para ver informações sobre como especificar caminhos com pastas do ambiente de desenvolvimento integrado.

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 de 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 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 estender os explorações entre projetos, no projeto importado será possível criar um arquivo de exploração separado e incluir esse arquivo em outros projetos. Para mais informações, consulte a seção Como incluir explorações em um modelo da página de documentação de parâmetros do include.

Incluindo arquivos que incluem outros arquivos

Quando você inclui um arquivo que inclui outros arquivos, tudo é resolvido antes que o arquivo seja transmitido para o próximo projeto que o inclui.

Por exemplo, se você importar um arquivo (A) de outro projeto (proj_A) no projeto atual, 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 referenciar arquivos de um projeto importado

Depois de importar um arquivo de visualização para seu projeto, use a sintaxe ${view_name.field_name} para fazer referência aos campos de visualização importada como se o arquivo de visualização fosse nativo desse 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 do modelo:

include: "//ga_360_block/ga_block.view"

Você usaria a sintaxe ${ga_block.hits_total} para referenciar o 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 seu projeto que pode ser reutilizado em todo o projeto. O subparâmetro export do parâmetro constant especifica se um valor de 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 de importação 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 o campo "Arquivo do manifesto de importação" não receber um valor, será usado o valor original do projeto importado.
  • 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 exibirá um erro.

Ao importar arquivos que fazem referência a uma constante para seu 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 a 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, o projeto usa o valor especificado com o parâmetro override_constant.

Constantes estão disponíveis somente para arquivos do projeto em que elas foram originalmente definidas. Portanto, as constantes definidas em um projeto com arquivos importados podem ser usadas apenas pelos arquivos importados, e não pelos arquivos definidos no projeto de importação.

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

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. Neste exemplo, vamos supor que os esquemas de dados sejam idênticos para cada banco de dados, e que seu objetivo seja 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 da visualização orders, que é definida da seguinte maneira:


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

O esquema em que a visualização orders é baseada é 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 precisará 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, você pode 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 para 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).

A substituição da constante schema_name no proj_a permite usar os campos definidos na visualização orders do 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 seu banco de dados.
  • Em proj_a, a visualização orders é baseada na tabela proj_a_schema.orders no seu banco de dados.