Importazione di file da altri progetti

Puoi importare file da altri progetti LookML e repository esterni nel progetto corrente. In questo modo puoi utilizzare file di modelli, file di visualizzazione e altri file in più progetti.

Esistono diversi casi d'uso per questo. Alcuni esempi:

  • Sviluppare un blocco di Looker installato senza dover apportare modifiche dirette. Se Looker apporta modifiche al blocco, puoi importarle perché tutto il codice LookML che hai aggiunto viene conservato in un repository separato.

  • Gestione di un progetto base generato automaticamente in base allo schema del database. Puoi inserire tutte le dimensioni, le misure e così via personalizzate in un progetto separato che importa tutto il LookML dal progetto generato automaticamente. Puoi rigenerare regolarmente il progetto di base man mano che lo schema del database cambia senza sovrascrivere tutto il LookML personalizzato.

  • Incapsulare gli oggetti condivisi in un unico progetto e poi importarli in più progetti. Ad esempio, se hai una tabella comune a più database, puoi inserire la relativa visualizzazione in un progetto e gestirla in un unico posto. Poi, fai in modo che più altri progetti la utilizzino importando la tabella in questi progetti.

Per importare file da un altro progetto, svolgi le seguenti attività:

  1. Crea un file manifest del progetto.
  2. Specifica i progetti locali o remoti da importare.
  3. Visualizza i file di un progetto importato.
  4. Includi i file di un progetto importato.

Potrai quindi fare riferimento ai campi dei file del progetto importato e sostituire i valori delle costanti definiti nel progetto importato, se le costanti consentono la sostituzione.

Creazione di un file manifest del progetto

Qualsiasi progetto che importa file da altri progetti deve avere un file manifest del progetto. Se il progetto non ha già un file manifest, puoi crearne uno dall'icona + nella parte superiore del browser dei file nell'IDE di Looker.

Per importare i progetti, specificali nel file manifest. Puoi specificare progetti locali o remoti, come descritto nelle sezioni seguenti.

Importazione di progetti locali

L'importazione di progetti locali può essere utilizzata solo se il progetto importato è presente nella stessa istanza di Looker. Inoltre, è consigliabile che gli sviluppatori dispongano delle autorizzazioni per i modelli per i modelli del progetto importato. Se gli sviluppatori dispongono delle autorizzazioni per i modelli nel progetto importato, il controllo delle versioni sarà dinamico, il che significa che le modifiche apportate al progetto importato influiranno immediatamente sul progetto che lo importa. In questo modo, gli sviluppatori possono convalidare le modifiche in entrambi i progetti prima di eseguire il push in produzione. Inoltre, per gli sviluppatori con autorizzazioni per i modelli in entrambi i progetti, i file del progetto importati rifletteranno lo stato della modalità di sviluppo dello sviluppatore. Pertanto, se lo sviluppatore è in modalità di sviluppo, l'IDE di Looker mostrerà la modalità di sviluppo dei file del progetto importato. Se lo sviluppatore è in modalità di produzione, l'IDE di Looker mostrerà la modalità di produzione del progetto importato.

Nel file manifest, il parametro project_name specifica il nome del progetto corrente (Looker compila automaticamente questo parametro quando crei il file manifest per il progetto). Per importare un progetto locale nel progetto corrente, utilizza uno o più parametri local_dependency per specificare il progetto o i progetti da importare:

# This project
project_name: "my_project"

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

Nei seguenti scenari, devi utilizzare l'importazione di progetti remoti anziché l'importazione di progetti locali:

  • Gli sviluppatori non dispongono delle autorizzazioni per i modelli nei modelli del progetto importato. In questo caso, Looker crea una copia della modalità di produzione del progetto importato e mostra la versione statica dei file nell'IDE. Questa versione statica non mostrerà mai la versione dei file in modalità di sviluppo e potrebbe anche essere obsoleta rispetto alla modalità di produzione corrente senza avvisare lo sviluppatore. È preferibile utilizzare l'importazione del progetto remoto e fornire un ref che specifichi un ramo Git o una release Git nel progetto remoto. In questo modo, Looker rileverà automaticamente i nuovi commit nel progetto remoto, in modo che gli sviluppatori ricevano un avviso e possano importare la versione più recente dei file del progetto remoto.
  • Gli sviluppatori devono sempre lavorare con la versione di produzione di un progetto importato.
  • Gli sviluppatori devono lavorare con una versione statica dei file del progetto importato.

Importazione di progetti remoti

In un'importazione remota, il progetto importato non deve trovarsi nella stessa istanza. Il progetto viene importato tramite il relativo repository Git remoto.

Per importare un repository remoto, utilizza il parametro remote_dependency per fornire le informazioni relative al repository remoto. Il parametro remote_dependency accetta le seguenti informazioni e sottoparametri:

  • Il nome del progetto importato, che può essere qualsiasi. Nel seguente esempio, il nome del progetto è ga_360_block. Utilizza questo nome nelle istruzioni include per fare riferimento ai file importati nei progetti LookML. Il nome viene utilizzato anche come nome della cartella nella cartella imported_projects dell'IDE di Looker.
  • Il parametro secondario url, in cui specifichi l'indirizzo del repository Git esterno. Utilizza l'URL principale del repository.
  • Il parametro secondario ref, in cui specifichi un ramo Git, un tag di release Git o l'SHA di un commit nel repository Git. Se vuoi utilizzare il controllo delle versioni statiche, puoi specificare un commit SHA in modo che le modifiche apportate al progetto importato non vengano applicate automaticamente al tuo progetto (questa è una buona opzione per i blocchi di Looker). In alternativa, puoi specificare un ramo Git o un tag di release Git se vuoi che Looker rilevi automaticamente i nuovi commit nel progetto remoto. Per saperne di più, consulta la sezione Rilevare automaticamente le nuove versioni di un progetto remoto in questa pagina.
  • Il parametro secondario override_constant, un parametro facoltativo che consente di sostituire il valore di una costante definita in un progetto importato.

Ecco un esempio di parametro remote_dependency in un file manifest del progetto. Questo esempio utilizza una connessione HTTPS:

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

Puoi anche utilizzare SSH:

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

Dopo aver aggiunto la dipendenza remota, potrebbe essere necessario configurare le credenziali di importazione per il progetto remoto. Consulta la sezione Configurazione delle credenziali di autenticazione per i repository remoti privati in questa pagina.

Rilevamento automatico delle nuove versioni di un progetto remoto

Puoi fare in modo che Looker rilevi automaticamente i nuovi commit nel progetto remoto se specifichi un ramo Git o un tag di release Git nel parametro secondario ref di remote_dependency nel file manifest.

Ad esempio, di seguito è riportata una dipendenza remota in cui il branch master è specificato nel parametro secondario ref:

remote_dependency: exchange_rate {
  url: "https://github.com/llooker/datablocks-exchangerate.git"
  ref: "master"
}

Successivamente, quando il ramo master viene aggiornato con nuovi commit, Looker rileva automaticamente le modifiche.

Ecco un esempio in cui è specificato il tag release v1.0:

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

Indipendentemente dal tipo di valore specificato per il parametro ref, anche un commit SHA, l'IDE mostrerà il pulsante Aggiorna dipendenze nella barra di navigazione del progetto in alto quando aggiungi un parametro remote_dependency al progetto.

Fai clic su Aggiorna dipendenze per importare i file del progetto remoto. Se si tratta della prima dipendenza remota che hai aggiunto al progetto, l'aggiornamento delle dipendenze richiederà anche a Looker di creare un file di blocco manifest. Looker utilizza il file di blocco manifest per monitorare la versione dei progetti remoti.

Se specifichi un ramo Git o un tag di release Git nel parametro secondario ref, Looker controllerà la presenza di nuovi commit ogni volta che l'IDE di Looker viene aggiornato, ad esempio quando uno sviluppatore di Looker attiva la modalità di sviluppo, esegue un'azione Git nell'IDE o aggiorna il browser.

Se esistono nuovi commit, Looker mostrerà l'opzione Aggiorna dipendenze nel riquadro delle azioni Git dell'IDE.

Seleziona l'opzione Aggiorna dipendenze per importare nel progetto i file del progetto remoto più recenti.

Una volta ottenuti i file più recenti, puoi convalidare il tuo codice LookML per verificare che tutti i riferimenti del progetto funzionino con i file del progetto remoto aggiornati. Puoi quindi correggere eventuali riferimenti non validi ed eseguire il deployment delle modifiche senza tempi di inattività per gli utenti.

File di blocco manifest

Looker utilizza il file di blocco manifest con il nome file manifest_lock.lkml per monitorare le versioni dei progetti importati da remoto. Il file di blocco del manifest è elencato nel riquadro del browser dei file dell'IDE di Looker.

Gli sviluppatori di Looker non devono creare o modificare il file di blocco manifest, poiché i file di blocco vengono gestiti automaticamente da Looker.

Il file manifest lock mostra ogni progetto remoto, rappresentato da una voce remote_dependency con i parametri secondari url e ref:

  • Il parametro remote_dependency indica il nome del progetto remoto specificato da uno sviluppatore di Looker nel file manifest.
  • Il parametro secondario url indica l'indirizzo del repository Git esterno specificato da uno sviluppatore di Looker nel file manifest.
  • Il parametro secondario ref mostra la versione del progetto (indicata da un commit SHA) utilizzata da Looker nel progetto:
    • Se il progetto remoto è stato definito nel file manifest con un ref di un branch Git o un tag di release Git, il parametro ref mostra la versione dei file (l'SHA del commit del progetto remoto) attualmente in uso dal progetto. Se sono presenti nuovi commit nel progetto remoto, Looker mostrerà il pulsante Aggiorna dipendenze nell'IDE per consentirti di importare i file del progetto remoto più recenti. Il valore ref nel file manifest lock verrà quindi aggiornato per mostrare l'SHA del commit più recente per quel ramo o tag di release.
    • Se il progetto remoto è stato definito nel file manifest con un ref di un commit SHA specifico, il parametro ref nel file manifest lock sarà lo stesso commit SHA.

Configurazione delle credenziali di autenticazione per i repository privati remoti

Per configurare le credenziali di autenticazione per i repository remoti privati, vai alla pagina Importa credenziali selezionando Impostazioni nel riquadro di navigazione a sinistra dell'IDE.

Le impostazioni Importa credenziali mostrano un elenco degli URL di ogni repository remoto definito nel file manifest del progetto, il tipo di autenticazione utilizzato per il repository (https o ssh) e se Looker può connettersi correttamente al repository.

Aggiunta delle credenziali di autenticazione

Per aggiungere le credenziali di autenticazione per un repository:

  1. Nella pagina Importa credenziali, sotto l'intestazione URL, passa il mouse sopra il nome di un repository per visualizzare i pulsanti Testa e Configura, quindi fai clic su Configura.

  2. Looker mostra la finestra di dialogo Configura l'autenticazione Git per consentirti di configurare le credenziali per il repository remoto. La finestra di dialogo indicherà il tipo di credenziali richieste per quel determinato repository.

    • Se il repository richiede un nome utente e una password (o un token di accesso personale) per l'autenticazione, inserisci il nome utente e la password o il token e fai clic su Salva modifiche.

    • Se il repository richiede una chiave SSH, ad esempio nell'esempio di utilizzo di SSH per importare un progetto remoto spiegato in precedenza in questa pagina, Looker mostra una finestra di dialogo che mostra la chiave SSH locale. Fai clic su Copia chiave per copiare la chiave SSH negli appunti e aggiungerla all'elenco di chiavi del repository.

  3. Dopo aver salvato le credenziali, fai clic su Test per verificare l'accesso di Looker al repository.

    Una volta superati i test di connessione e connesso al repository, nella sezione Importa credenziali viene visualizzato un segno di spunta verde accanto al nome del repository.

Modifica delle credenziali di autenticazione

Per modificare le credenziali di autenticazione per un repository:

  1. Per visualizzare i pulsanti Test e Modifica, tieni premuto il cursore del mouse sopra un repository in cui sono già configurate le credenziali di autenticazione e fai clic su Modifica.

  2. Se il repository richiede un nome utente e una password (o un token di accesso personale) per l'autenticazione, fai clic su Svuota credenziali e, nella finestra di dialogo di conferma, fai clic su Sì, svuota credenziali.

  3. Inserisci le nuove credenziali nella finestra di dialogo Configura autenticazione Git e fai clic su Salva modifiche.

Visualizzazione dei file di un progetto importato

L'IDE di Looker mostra i file del progetto importati nella cartella imported_projects del riquadro di navigazione a sinistra. Puoi selezionare un file di progetto importato per visualizzarne i contenuti.

I file dei progetti locali e dei progetti remoti sono elencati nella cartella imported_projects.

Puoi anche visualizzare gli oggetti dei file di progetto importati inclusi nel progetto attivo dal browser degli oggetti. Accedi al browser degli oggetti dalla barra di navigazione dell'IDE di Looker.

Inoltre, gli utenti con autorizzazione develop possono utilizzare il riquadro dei metadati per visualizzare informazioni sugli oggetti dei progetti importati, inclusi i link per accedere al file importato in cui è definito l'oggetto. Per ulteriori informazioni, consulta la pagina della documentazione relativa ai metadati per gli oggetti LookML.

Includere file di un progetto importato

Il parametro include in un file del modello specifica i file di progetto che saranno disponibili per il modello. Dopo aver specificato un progetto importato locale o remoto nel file manifest, puoi utilizzare il parametro include in un file del modello per specificare i file del progetto importato. Possono essere inclusi solo i file il cui progetto è elencato nel file manifest.

Per include un file da un altro progetto, utilizza il nome file con due barre (//) e il nome del progetto importato. Segui il nome del progetto importato con una singola barra (/) e il percorso completo del file da includere.

Ad esempio, questi comandi include indicano il file della visualizzazione users del progetto importato e_flights e la visualizzazione orders del progetto importato e_commerce:

include: "//e_flights/views/users.view.lkml"
include: "//e_commerce/public/orders.view.lkml"

Per informazioni su come specificare i percorsi con le cartelle IDE abilitate, consulta la sezione Sintassi dei percorsi della pagina del parametro include.

Puoi utilizzare i caratteri jolly per includere più file. Ad esempio, per includere tutti i file di visualizzazione nella directory /views/ del progetto e_flights importato:

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

Inoltre, puoi utilizzare i caratteri jolly per limitare l'ambito a livelli di directory specifici o a directory ricorsive nel progetto importato:

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

Per informazioni sull'utilizzo dei caratteri jolly con le cartelle IDE abilitate, consulta la sezione Esempi di caratteri jolly della pagina del parametro include.

Inclusione dei file del modello

Non puoi includere un file modello di un altro progetto. Se invece vuoi riutilizzare, perfezionare o estendere le esplorazioni in più progetti, nel progetto importato puoi creare un file di esplorazione separato, quindi includerlo in altri progetti. Per ulteriori informazioni, consulta la sezione Inclusione di esplorazioni in un modello della pagina della documentazione del parametro include.

Includi file che includono altri file

Quando includi un file che include altri file, tutte le inclusioni vengono risolte prima che il file venga trasmesso al progetto successivo che lo include.

Ad esempio, se nel progetto corrente importi un file (A) da un altro progetto (proj_A) e il file importato contiene un parametro include che include il file B del progetto proj_B, il file B verrà incluso nel file A prima che il file A venga importato nel progetto corrente.

Importazione dei file di dati

I file archiviati nella sezione Dati di un progetto non vengono importati. Per fare riferimento a un file di dati di un progetto importato, ad esempio nel parametro map_layer, utilizza il percorso completo e il nome file del file. Ad esempio:

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

Fare riferimento ai file di un progetto importato

Dopo aver importato un file di visualizzazione nel progetto, puoi utilizzare la sintassi ${view_name.field_name} per fare riferimento ai campi della visualizzazione importata come se il file della visualizzazione facesse parte del progetto. Ad esempio, supponiamo che tu abbia importato il progetto ga_360_block nel file manifest del progetto e che nel file del modello sia presente la seguente dichiarazione ga_360_block:include

include: "//ga_360_block/ga_block.view"

Dovresti utilizzare la sintassi ${ga_block.hits_total} per fare riferimento al campo hits_total dalla visualizzazione ga_block inclusa.

Utilizzo delle costanti nei file di un progetto importato

Le costanti LookML ti consentono di definire un valore nel file manifest del progetto che può essere riutilizzato in tutto il progetto. Il parametro secondario export del parametro constant specifica se il valore di una costante può essere ignorato quando i file che fanno riferimento a quella costante vengono importati in un altro progetto.

Il parametro export ha i seguenti valori possibili:

  • none: il valore predefinito per export. Il valore della costante non può essere sostituito nel progetto di importazione. Il progetto di importazione utilizza il valore costante specificato nel file manifest del progetto importato.
  • override_optional: il valore della costante può essere eventualmente ignorato nel progetto di importazione. Se non viene fornito un valore nel file manifest del progetto di importazione, viene utilizzato il valore originale del progetto importato.
  • override_required: il progetto di importazione deve sostituire il valore costante specificato originariamente nel file manifest del progetto importato. Se nel progetto di importazione non viene fornito un nuovo valore costante, Looker mostrerà un errore.

Quando importi nel progetto file che fanno riferimento a una costante, puoi utilizzare il parametro secondario override_constant di local_dependency o remote_dependency nel file manifest del progetto per fornire un nuovo valore per la costante, a condizione che export sia impostato su override_optional o override_required nel progetto originale. Quando sostituisci il valore di una costante di un progetto importato, il progetto utilizzerà il valore specificato con il parametro override_constant.

Ad esempio, supponiamo che tu stia gestendo più database su un'unica istanza di Looker, con un progetto separato per ogni database. Supponiamo inoltre che gli schemi di dati siano identici per ogni database e che il tuo obiettivo sia definire un'analisi una volta e applicarla a ogni set di dati.

In questo esempio, supponiamo che proj_core sia il progetto di base in cui hai definito le viste da importare in altri progetti. Inoltre, una delle visualizzazioni che vuoi importare è la visualizzazione orders, definita come segue:


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

Lo schema su cui si basa la visualizzazione orders è specificato nel parametro sql_table_name utilizzando la costante schema_name, definita nel file manifest proj_core. Nell'esempio seguente, poiché la costante schema_name è impostata su export: override_required, qualsiasi progetto che importa schema_name deve sostituire il relativo valore utilizzando il parametro override_constant:


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

Ad esempio, supponiamo che tu voglia importare la visualizzazione orders in un progetto locale denominato proj_a. Nel database per proj_a è presente anche una tabella denominata orders con una struttura identica a quella della tabella orders nel progetto di base proj_core.

Poiché proj_core e proj_a si trovano nella stessa istanza, puoi importare la visualizzazione orders in proj_a utilizzando local_dependency. Utilizzando il parametro secondario override_constant di local_dependency, puoi aggiornare la costante schema_name in modo che indichi lo schema proj_a_schema nel file manifest per proj_a:


project_name: "proj_a"

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

In questo esempio, poiché la costante schema_name è impostata su export: override_required in project_core, Looker mostrerà un errore se non ne sostituisci il valore in proj_a (il progetto di importazione).

L'override della costante schema_name in proj_a ti consente di utilizzare i campi definiti nella visualizzazione orders in proj_core, anziché creare un nuovo file di visualizzazione e definire i campi da zero. In questo esempio, la visualizzazione orders corrisponde a una tabella diversa per ogni progetto:

  • In proj_core, la vista orders si basa sulla tabella proj_core_schema.orders nel database.
  • In proj_a, la vista orders si basa sulla tabella proj_a_schema.orders nel database.