Importazione di file da altri progetti

La funzionalità Importazione locale del progetto è una funzionalità sperimentale di Labs che importa i file dai progetti LookML locali. Le funzionalità sperimentali non sono completamente sviluppate e potrebbero essere modificate o rimosse in modo significativo.

L'importazione di file da progetti LookML remoti o locali non è attualmente compatibile con la localizzazione del modello.

Puoi importare nel tuo progetto corrente file da altri progetti LookML e repository esterni. In questo modo puoi utilizzare i file modello, visualizzare i file e altri file in più di un progetto.

Esistono diversi casi d'uso. Alcuni esempi:

  • Esecuzione su un Looker Block installato senza dover apportare modifiche dirette. Se Looker apporta modifiche al blocco, puoi facilmente importarle perché tutti i LookML che hai aggiunto vengono conservati in un repository separato.

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

  • Incapsulare gli oggetti condivisi in un singolo progetto, quindi importarli in più altri progetti. Ad esempio, se hai una tabella comune a più database, potresti inserire la visualizzazione per quel progetto in un unico progetto e mantenerla in un unico posto. Quindi, puoi farne utilizzare altri progetti importando la tabella al loro interno.

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

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

Se le costanti consentono la sostituzione, potrai fare riferimento ai campi dei file del progetto importati e sostituire i valori delle costanti definite nel progetto importato.

Creazione di un file manifest del progetto

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

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

Importazione di progetti locali

L'amministratore di Looker deve abilitare la funzionalità Labs di Local Project Import per consentire l'importazione di file locali nel progetto.

L'importazione dei progetti locali può essere utilizzata solo se il progetto importato è presente nella stessa istanza di Looker. È inoltre consigliabile che gli sviluppatori dispongano di autorizzazioni per i modelli per i modelli di progetto importati. Se gli sviluppatori hanno le autorizzazioni dei modelli nel progetto importato, il controllo delle versioni sarà dinamico, il che significa che le modifiche al progetto importato avranno effetto immediato sul progetto che lo importa. Questo consente agli sviluppatori di convalidare le modifiche in entrambi i progetti prima di passare alla produzione. Inoltre, per gli sviluppatori con autorizzazioni per i modelli in entrambi i progetti, i file di progetto importati riflettono lo stato della modalità di sviluppo dello sviluppatore. Pertanto, se lo sviluppatore è in modalità sviluppatore, l'IDE di Looker mostrerà la modalità di sviluppo dei file del progetto importato. Se lo sviluppatore è in modalità produzione, l'IDE di Looker mostrerà la modalità di produzione del progetto importato.

Per importare a livello locale, utilizza il parametro project_name per specificare il 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"
}

Negli scenari seguenti, devi utilizzare l'importazione di progetti da remoto anziché l'importazione di progetti locali:

  • I tuoi sviluppatori non dispongono delle autorizzazioni del modello nei modelli del progetto importati. In questo caso, Looker crea un clone della modalità di produzione del progetto importato e visualizza la versione statica dei file nell'IDE. Questa versione statica non mostrerà mai la versione in modalità di sviluppo dei file e potrebbe anche essere obsoleta con l'attuale modalità di produzione senza avvisare lo sviluppatore. È preferibile utilizzare l'importazione dei prodotti remoti e fornire un ref che specifichi un ramo Git o una release Git nel progetto remoto. In questo caso, Looker rileverà automaticamente i nuovi commit nel progetto remoto, in modo che gli sviluppatori vengano avvisati e potranno visualizzare la versione più recente dei file di progetto remoto.
  • I tuoi sviluppatori devono sempre lavorare con la versione di produzione di un progetto importato.
  • I tuoi 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 necessariamente trovarsi nella stessa istanza. ma viene importato tramite il repository Git remoto.

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

  • Il nome del progetto importato, che può avere qualsiasi nome. Nell'esempio seguente, il nome del progetto è ga_360_block. Puoi utilizzare questo nome nelle istruzioni include per fare riferimento ai file importati nei progetti LookML. Il nome è utilizzato anche come nome della cartella nella cartella imported_projects dell'IDE di Looker.
  • Il sottoparametro url, in cui specifichi l'indirizzo del repository Git esterno. Utilizza l'URL principale del repository.
  • Il sottoparametro ref, in cui specifichi un ramo Git, un tag di rilascio Git o l'SHA di un commit nel repository Git. Se vuoi eseguire il controllo delle versioni, puoi specificare un commit SHA, in modo che le modifiche al progetto importato non si riflettano automaticamente nel tuo progetto (questa è una buona opzione per Looker Blocks). In alternativa, puoi specificare un ramo Git o un tag di rilascio Git se vuoi che Looker rilevi automaticamente i nuovi commit nel progetto remoto. Per saperne di più, consulta la sezione Rilevamento automatico delle nuove versioni di un progetto remoto in questa pagina.
  • Il sottoparametro override_constant, che è un sottoparametro facoltativo che ti 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. In questo esempio viene utilizzata 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, vedi 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 rilascio Git nel sottoparametro ref di remote_dependency nel tuo file manifest.

Ad esempio, ecco una dipendenza remota in cui il ramo master è specificato nel sottoparametro 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 di release v1.0:

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

Indipendentemente dal tipo di ref specificato, anche da un'SHA di commit, l'IDE mostrerà il pulsante Aggiorna dipendenze quando aggiungi un parametro remote_dependency al progetto:

Fai clic sul pulsante per visualizzare i file di progetto da remoto. Se questa è la prima dipendenza remota che hai aggiunto al progetto, l'aggiornamento delle dipendenze chiederà anche a Looker di creare un file di blocco manifest. Looker utilizza il file di blocco del manifest per tenere traccia della versione dei progetti remoti.

Se specifichi un ramo Git o un tag di rilascio Git nel sottoparametro ref, Looker controlla se sono presenti nuovi commit ogni volta che l'IDE di Looker viene aggiornato, cosa che accade quando uno sviluppatore di Looker passa alla modalità di sviluppo, esegue un'azione Git nell'IDE o aggiorna il browser.

Se sono presenti nuovi commit, Looker mostrerà l'opzione Update Dependencies nel riquadro delle azioni Git dell'IDE:

Seleziona l'opzione Update Dependencies per importare i file di progetti remoti più recenti nel tuo progetto.

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

File di blocco del manifest

Looker utilizza il file di blocco del manifest per tenere traccia delle versioni dei progetti importati da remoto:

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

Il file di blocco del file manifest mostra ciascun progetto remoto, rappresentato da una voce remote_dependency con i sottoparametri url e ref:

  • Il parametro remote_dependency indica il nome del progetto remoto che uno sviluppatore Looker ha specificato nel file manifest.
  • Il sottoparametro url indica l'indirizzo del repository Git esterno specificato da uno sviluppatore Looker nel file manifest.
  • Il sottoparametro ref mostra la versione del progetto (indicata da un commit SHA) che Looker sta utilizzando nel tuo progetto:
    • Se il progetto remoto è stato definito nel file manifest con un ref di un ramo Git o un tag di rilascio Git, il parametro ref mostra la versione dei file (il SHA commit di progetto remoto) che il progetto sta utilizzando attualmente. Se sono presenti nuovi commit nel progetto remoto, Looker visualizza il pulsante Update Dependencies nell'IDE per consentirti di importare i file di progetto remoto più recenti. Il valore ref nel file di blocco del manifest verrà quindi aggiornato per mostrare l'ultimo commit SHA per quel ramo o tag di rilascio.
    • Se il progetto remoto è stato definito nel file manifest con un ref di un commit SHA specifico, il parametro ref nel file di blocco del manifest sarà lo stesso SHA.

Configurazione delle credenziali di autenticazione per i repository privati remoti

Le impostazioni di Importa credenziali mostrano l'elenco degli URL di ciascun repository remoto definito nel file manifest del progetto, il tipo di autenticazione utilizzato per il repository (https o ssh) e indica se Looker è in grado di connettersi al repository.

Aggiunta delle credenziali di autenticazione

Per aggiungere credenziali di autenticazione per un repository:

  1. Passa il mouse sopra il nome di un repository per visualizzare i pulsanti Test e Configura e fai clic su Configura.

  2. Looker visualizza una finestra di dialogo che consente di configurare le credenziali per il repository remoto. La finestra di dialogo indicherà il tipo di credenziali necessarie per quel particolare 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 in questo esempio, Looker mostra una finestra di dialogo che mostra la tua chiave SSH locale. Fai clic su Copia chiave per copiare la chiave SSH negli appunti e aggiungerla all'elenco di chiavi del repository.

    Se il tuo progetto remoto è un repository LookML, potrebbero esistere già chiavi SSH, ad esempio una chiave SSH che è stata aggiunta al repository quando il progetto LookML era stato originariamente connesso a Git. Lascia eventuali chiavi SSH esistenti quando aggiungi la nuova chiave SSH al repository.

  3. Dopo aver salvato le credenziali, fai clic sul pulsante Test per testare l'accesso di Looker al repository:

    Dopo aver superato i test di connessione e aver effettuato la connessione al repository, la sezione Import Credentials (Importa credenziali) mostra un segno di spunta verde accanto al nome del repository.

Modificare le credenziali di autenticazione

Per modificare le credenziali di autenticazione per un repository:

  1. Passa il mouse sopra un repository che ha già configurato le credenziali di autenticazione per visualizzare i pulsanti Test e Modifica 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 Cancella credenziali e, nella finestra popup di conferma, fai clic su Sì, cancella credenziali.

  3. Inserisci le nuove credenziali nel popup Configura autenticazione Git e fai clic su Salva modifiche.

Visualizzazione di file da un progetto importato

L'IDE di Looker visualizza i file di progetto importati nella cartella imported_projects del riquadro di navigazione a sinistra. Puoi fare clic su un file di progetto importato per visualizzarne i contenuti:

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

Poiché non possono essere modificati, i file dei progetti importati non sono visibili quando esegui la modifica collettiva dei file nell'IDE.

Puoi anche visualizzare oggetti dai file di progetto importati che sono 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 nel punto in cui è definito l'oggetto. Per ulteriori informazioni, consulta la pagina della documentazione Metadati per oggetti LookML.

Sono inclusi i file di un progetto importato

Il parametro include in un file di modello specifica i file di progetto che saranno disponibili per tale modello. Una volta specificato un progetto locale o remoto importato nel file manifest, puoi utilizzare il parametro include in un file modello per specificare file dal progetto importato. È possibile includere solo i file il cui progetto è elencato nel file manifest.

Per include un file di un altro progetto, utilizza il nome del 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, i seguenti comandi include indicano il file di vista users del progetto importato e_flights e la vista 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 dell'IDE attivate, consulta la sezione Sintassi del percorso della pagina della documentazione relativa all'utilizzo delle cartelle nell'IDE.

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

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

Inoltre, puoi utilizzare i caratteri jolly per definire un ambito a livelli di directory specifici o a directory ricorrenti nel progetto importato:

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

Per informazioni sull'utilizzo dei caratteri jolly con le cartelle IDE, consulta la sezione Esempi di caratteri jolly nella pagina della documentazione relativa all'utilizzo delle cartelle nell'IDE.

Inclusi i file modello

Non puoi includere un file modello da un altro progetto. Se vuoi riutilizzare, perfezionare o estendere le esplorazioni di più progetti, nel progetto importato puoi creare un file Esplora separato e includerlo in altri progetti. Per saperne di più, consulta la sezione Inclusione di esplorazioni in un modello della pagina della documentazione relativa al parametro include.

Sono inclusi file che includono altri file

Quando includi un file che include altri file, tutti i problemi vengono risolti prima che il file venga passato 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 di importare il file A nel progetto corrente.

Importazione di file di dati

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

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

Fare riferimento a file da un progetto importato

Dopo aver importato un file della vista nel progetto, puoi utilizzare la sintassi ${view_name.field_name} per fare riferimento ai campi delle viste importate come se il file della vista fosse nativo di tale progetto. Ad esempio, supponiamo di aver importato il progetto ga_360_block nel file manifest del progetto e che nel file di modello sia presente la seguente istruzione include:

include: "//ga_360_block/ga_block.view"

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

Utilizzo delle costanti nei file di un progetto importato

Le costanti LookML consentono di definire un valore nel file manifest del progetto che può essere riutilizzato in tutto il progetto. Il sottoparametro export del parametro constant specifica se è possibile sostituire un valore di costante 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 di 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 facoltativamente sostituito nel progetto di importazione. Se nel file manifest del progetto di importazione non viene fornito un valore, viene utilizzato il valore originale del progetto importato.
  • override_required: il progetto di importazione deve sostituire il valore costante originariamente specificato nel file manifest del progetto importato. Se nel progetto di importazione non viene fornito un nuovo valore costante, Looker mostrerà un errore.

Quando importi file che fanno riferimento a una costante nel tuo progetto, 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, purché la costante abbia export impostato su override_optional o override_required nel progetto originale. Quando esegui l'override del valore di una costante di un progetto importato, il progetto utilizzerà il valore specificato con il parametro override_constant.

Le costanti sono disponibili solo per i file del progetto in cui sono state definite in origine. Pertanto, le costanti definite in un progetto di cui hai importato i file possono essere utilizzate solo dai file importati e non dai file definiti nel progetto di importazione.

Se vuoi utilizzare una costante nei file del progetto di importazione, devi usare il parametro constant per definire una nuova costante nel file manifest del progetto di importazione. Una costante definita in questo modo sarà disponibile solo per i file definiti nel progetto di importazione.

Ad esempio, supponiamo che tu gestisca più database su una singola istanza di Looker, con un progetto separato per ogni database. In questo esempio, supponiamo anche che gli schemi di dati siano identici per ogni database e che il tuo obiettivo sia definire una volta un'analisi e applicarla a ogni set di dati.

Supponi che proj_core sia il progetto di base in cui hai definito le viste che vuoi importare in altri progetti. Inoltre, una delle viste che vuoi importare è la vista orders, che viene definita come segue:


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

Lo schema su cui si basa la vista 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 ignorarne il valore utilizzando il parametro override_constant:


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

Per questo esempio, supponiamo che tu voglia importare la visualizzazione orders in un progetto locale chiamato 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 vista orders in proj_a utilizzando local_dependency. Utilizzando il sottoparametro override_constant di local_dependency, puoi quindi aggiornare la costante schema_name per fare riferimento allo schema proj_a_schema nel file manifest di 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 visualizza 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 vista orders in proj_core, anziché creare un nuovo file di vista e definire i campi da zero. In questo esempio, la vista orders corrisponde a una tabella diversa per ogni progetto:

  • In proj_core, la visualizzazione orders si basa sulla tabella proj_core_schema.orders del database.
  • In proj_a, la visualizzazione orders si basa sulla tabella proj_a_schema.orders del database.