Como importar arquivos de outros projetos

É possível importar arquivos de outros projetos do LookML e repositórios externos para o projeto atual, o que permite usar arquivos de modelo, arquivos de visualização e outros arquivos em mais de um projeto. Os projetos importados são somente leitura. Se você quiser editar os arquivos, faça isso no projeto LookML deles ou em outro editor conectado ao repositório Git dos arquivos.

Há vários casos de uso para importar arquivos para seu projeto do LookML. Confira alguns exemplos:

• Criar com base em um Bloco do Looker instalado sem precisar fazer mudanças diretas nele. Se o Looker fizer mudanças no bloco, você poderá extrair as alterações porque toda a LookML adicionada a ele é mantida em um repositório separado.

• Manter um projeto de base gerado automaticamente com base no esquema do banco de dados. Você pode colocar todas as dimensões e métricas personalizadas e semelhantes em um projeto separado que importa toda a LookML do projeto gerado automaticamente. É possível regenerar regularmente o projeto de base à medida que o esquema do banco de dados muda, sem substituir toda a LookML personalizada.

• Encapsular objetos compartilhados em um único projeto e 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 em um só lugar. Em seguida, faça com que vários outros projetos usem a tabela importando-a para eles.

Para importar arquivos de outro projeto, faça o seguinte:

1. Crie um arquivo de manifesto do projeto.
2. Especifique os projetos local ou remoto que você quer importar.
3. Ver 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 de constantes definidos no projeto importado, se as constantes permitirem substituição.

Como criar um arquivo de manifesto do projeto

Qualquer projeto que importe arquivos de outros projetos precisa ter um arquivo de manifesto. 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 IDE do Looker.

Para importar projetos, especifique-os no manifesto. Você pode 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 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ões será dinâmico. Isso significa que 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 importados vão refletir o status do Modo de desenvolvimento do desenvolvedor. Assim, 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 automaticamente esse parâmetro 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 o projeto ou os projetos a serem importados:

# This project
project_name: "my_project"

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

Nos seguintes cenários, 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 essa versão estática dos arquivos no IDE. Essa versão estática nunca mostraria a versão do modo de desenvolvimento dos arquivos e também poderia estar desatualizada com o modo de produção atual sem alertar o desenvolvedor. É melhor usar a importação de projetos remotos 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 novos commits no projeto remoto. Assim, os desenvolvedores serão alertados e poderão trazer 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.

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 necessárias. 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 a seguir, o nome do projeto é ga_360_block. Você usa esse nome em instruções include para fazer referência aos arquivos importados em projetos do LookML. O nome também é usado como o nome da pasta em 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 um commit no repositório do Git. Você pode especificar um SHA de commit se quiser o controle de versão estático, para que as mudanças no projeto importado não sejam refletidas automaticamente no seu projeto. Essa é uma boa opção para blocos do Looker. Ou você pode especificar uma ramificação ou tag de lançamento do Git se quiser que o Looker detecte automaticamente novos commits 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 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 do projeto remoto. Consulte a seção 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 novos commits no projeto remoto se você especificar uma ramificação ou tag de lançamento 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"
}

Depois disso, quando a ramificação master for atualizada com novos commits, o Looker vai detectar as mudanças automaticamente.

Este é 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"
}

Independente do tipo de valor especificado para o parâmetro ref, até mesmo um SHA de commit, 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 ao projeto.

Clique em Atualizar dependências para trazer os arquivos do projeto remoto. Se esta for a primeira dependência remota adicionada ao projeto, a atualização 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 novos commits sempre que o IDE do Looker for atualizado. Isso acontece quando um desenvolvedor do Looker entra no modo de desenvolvimento, realiza uma ação do Git no IDE ou atualiza o navegador.

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

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

Depois de ter os arquivos mais recentes, valide o LookML para verificar se todas as referências do projeto funcionam com os arquivos do projeto remoto atualizados. Em seguida, corrija as referências quebradas e implante as mudanças sem inatividade para os usuários.

Arquivo de bloqueio de manifesto

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

Os desenvolvedores do Looker não precisam criar nem editar o arquivo de bloqueio do manifesto, já que ele é gerenciado 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 especificado por um desenvolvedor do Looker 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 commit) que o Looker está usando no seu 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 commit 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 IDE 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 da ramificação ou tag de lançamento.
  • Se o projeto remoto foi definido no arquivo de manifesto com um ref de um SHA de commit específico, o parâmetro ref no arquivo de bloqueio do manifesto será o mesmo SHA de commit.

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 tune no painel de navegação à esquerda do ambiente de desenvolvimento integrado.

As configurações de Importar credenciais mostram uma lista dos URLs de 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. Na página Importar credenciais, abaixo do título URL, passe o cursor sobre o nome de um repositório para mostrar os botões Testar e Configurar. Clique em Configurar.

   

2. O Looker mostra a caixa de diálogo Configurar autenticação do Git para 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 token de acesso pessoal) para 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 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 sua chave SSH local. Clique em Copiar chave para copiar a chave SSH para a área de transferência e adicione-a à 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 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. Para mostrar 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 usuário e uma senha (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. Insira as novas credenciais na caixa de diálogo Configurar autenticação do Git e clique em Salvar alterações.

Como visualizar arquivos de um projeto importado

O IDE do Looker mostra os arquivos de projeto 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.

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

Você também pode ver objetos de arquivos de projeto importados 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 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 está definido. Consulte a página de documentação Metadados para objetos LookML para mais informações.

Incluindo 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. Só é possível incluir arquivos cujo projeto esteja listado no arquivo de manifesto.

Para include 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 do caminho na página de parâmetros include para informações sobre como especificar caminhos com pastas do ambiente de desenvolvimento integrado ativadas.

É possível 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 diretórios recursivos no projeto importado:

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

Consulte a seção Exemplos de caracteres curinga na página de parâmetros include para informações sobre como usar caracteres curinga com pastas do ambiente de desenvolvimento integrado ativadas.

Incluir arquivos de modelo

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

Incluindo 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 transmitido 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 tiver um parâmetro include que inclui o arquivo B do projeto proj_B, o arquivo B será incluído no arquivo A antes de ser importado para o projeto atual.A

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 seu projeto, use a sintaxe ${view_name.field_name} para referenciar os campos da visualização importada como se o arquivo de visualização fizesse parte desse projeto. Por exemplo, digamos que você tenha importado o projeto ga_360_block no arquivo de manifesto do seu 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

Com as constantes do LookML, é possível 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 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. 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 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 originalmente especificado 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 referenciam uma constante para seu projeto, use 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 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.

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. Também suponha que os esquemas de dados sejam idênticos para cada banco de dados e que sua meta seja definir uma análise uma vez e aplicá-la a cada conjunto de dados.

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

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 a seguir, 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
}

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 de 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, é 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 dela em proj_a (o projeto de importação).

Ao substituir a constante schema_name em proj_a, é possível 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.