Tieni presente che stai visualizzando la documentazione di Looker. Per la documentazione di Looker Studio, visita https://support.google.com/looker-studio.

Utilizzo e flusso di lavoro di CI/CD di Looker

Questa pagina spiega come utilizzare un flusso di lavoro CI/CD in Looker dopo che un flusso di lavoro è stato installato e configurato.

Queste istruzioni utilizzano un sistema a tre livelli che comprende sviluppo, QA e produzione. Tuttavia, puoi applicare gli stessi principi a un sistema a due o a quattro livelli.

Queste istruzioni presuppongono anche l'utilizzo di GitHub come provider Git. Puoi utilizzare altri provider Git per creare un flusso di lavoro CI/CD, ma devi disporre delle competenze necessarie per modificare queste istruzioni per il tuo provider.

Panoramica del flusso di lavoro

Gli sviluppatori LookML iniziano scrivendo codice nel ramo di sviluppo, che in genere ha un nome simile a dev-my-user-ydnv, testa le modifiche con Spectacles ed esegui il commit del codice. Infine, apre una richiesta di pull per unire il proprio codice al ramo main.

Quando la richiesta di pull viene aperta, lo sviluppatore viene indirizzato a GitHub. Lo sviluppatore dovrebbe scrivere un titolo PR significativo utilizzando uno stile convenzionale di commit e aggiungere alla descrizione un commento da includere nel log delle modifiche. I risultati dei test Spectacles devono essere aggiunti come commenti al PR.

In seguito, lo sviluppatore deve selezionare un recensore in GitHub. Il revisore riceverà una notifica e potrà aggiungere la sua recensione al PR. Se il revisore approva la modifica, il PR viene unito al ramo main. Viene chiamato un WebHook e l'ambiente di sviluppo vede ora il cambiamento.

Verrà eseguita automaticamente l'automazione della release che aprirà un secondo PR per creare una nuova release con tag. Oppure, se esiste già un PR aperto a questo scopo, Rilascia un PR per aggiornarlo. Alla release PR sono associati un numero di versione e un log delle modifiche che include i titoli e le descrizioni delle modifiche incluse.

Quando il PR generato per la release viene approvato e unito, viene generato un nuovo tag di versione e il log delle modifiche viene unito al ramo main. Le istanze di QA e produzione di Looker possono selezionare questa versione utilizzando la modalità di deployment avanzata.

Best practice per la numerazione delle release e la denominazione dei commit

Le release e i relativi tag associati possono essere denominati e numerati nel modo più appropriato per il tuo ambiente. Tuttavia, in questo caso viene utilizzato il controllo delle versioni semantico, vivamente consigliato perché funziona bene con il plug-in Release Release.

Nel controllo delle versioni semantico, la versione è composta da tre numeri separati da punti: MAJOR.MINOR.PATCH

Il valore PATCH viene incrementato ogni volta che una release corregge un bug
Il valore MINOR viene incrementato e il valore PATCH viene reimpostato su zero ogni volta che la release aggiunge o perfeziona una funzionalità, pur essendo compatibile con le versioni precedenti
MAJOR viene incrementato e sia MINOR che PATCH vengono impostati su zero quando viene aggiunta una funzionalità non compatibile con le versioni precedenti

I comitati convenzionali sono un sistema di denominazione dei commit in base all'impatto che hanno sugli utenti finali. Sebbene non sia obbligatorio, l'utilizzo della denominazione convenzionale dei commit è utile anche per il plug-in Release Release.

Nella denominazione convenzionale del commit, ogni messaggio di commit è anteposto a un indicatore dell'ambito della modifica:

Con fix: è stata indicata una correzione di bug, ad esempio fix: set proper currency symbol on sale_amt format
Con feat: viene indicata una nuova funzionalità come feat: added explore for sales by territory
Una funzionalità con una modifica che provoca un errore è indicata da feat!: come feat!: rewrote sales explore to use the new calendar view
Quando i documenti vengono aggiornati, ma il LookML non viene modificato, il messaggio di commit inizia con doc:

Se i commit convenzionali vengono utilizzati in modo coerente, la determinazione del numero semantico da utilizzare successivamente è generalmente semplice. Se il log di commit è composto solo da fix: e doc: commit, il valore di PATCH deve essere incrementato. In presenza di un commit feat:, il valore MINOR deve essere incrementato. Se è presente un valore feat!:, il valore di MAJOR deve essere incrementato. Il plug-in Release Release può persino generare un file CHANGELOG e taggare la release automaticamente.

Utilizzo della modalità di deployment avanzata

Dopo aver apportato e inviato le modifiche come PR nell'istanza di sviluppo, il plug-in Release Release tagga le modifiche con un tag di versione, ad esempio v1.2.3. La modalità di deployment avanzata di Looker rende quindi queste versioni disponibili nell'interfaccia utente di Looker per il QA e le istanze di produzione.

Per eseguire il deployment di una modifica, scegli Deployment Manager dall'IDE di Looker:

Località di Looker Deployment Manager nell'ambiente IDE.

Fai clic sul link Seleziona commit in alto a destra in Deployment Manager. Successivamente, seleziona il menu con tre puntini associato al tag di cui vuoi eseguire il deployment e scegli Esegui il deployment nell'ambiente:

UI di Looker Deployment Manager per il deployment nell'ambiente.

Non è necessario aggiungere nuovamente i tag al deployment, quindi scegli Esegui il deployment senza tagging e premi il pulsante Esegui il deployment nell'ambiente:

UI di Looker Deployment Manager per il deployment senza tagging.

Infine, esegui il push in produzione utilizzando Deployment Manager.

Uso di Occhiali

Gli occhiali possono essere utilizzati da ogni sviluppatore per verificare le modifiche mentre si trova ancora nel ramo di sviluppo. Spectacles offre quattro diversi strumenti di convalida:

SQL
LookML
Contenuti
Dichiara

Quando uno sviluppatore invia una richiesta di pull, è buona norma eseguire questi test e copiare i risultati in un commento nel PR.

Strumento di convalida SQL

Lo strumento di convalida SQL testa ogni esplorazione per garantire che tutti i campi definiti nelle viste LookML corrispondano a colonne SQL effettive o a espressioni SQL valide nel database. Lo strumento di convalida SQL viene chiamato come indicato di seguito:

$ spectacles sql --config-file config-dev.yaml \
    --project PROJECT_NAME \
    --explores MODEL_NAME/EXPLORE_NAME \
    --branch DEV_BRANCH_NAME

Ad esempio:

$ spectacles sql --config-file config-dev.yaml \
    --project thelook_cicd \
    --explores thelook_cicd/users \
    --branch dev-my-user-ydnv

Connected to Looker version 23.18.60 using Looker API 4.0

=================== Testing 1/1 explores [concurrency = 10] ===================

✓ thelook_cicd.users passed

Completed SQL validation in 1 minute and 7 seconds.

Strumento di convalida LookML

Lo strumento di convalida LookML assicura che le modifiche LookML siano valide e che non presentino errori di sintassi. Si chiama come mostrato di seguito:

$ spectacles lookml --config-file config-dev.yaml \
    --project PROJECT_NAME \
    --branch DEV_BRANCH_NAME

Ad esempio:

$ spectacles lookml --config-file config-dev.yaml \
    --project thelook_cicd \
    --branch dev-my-user-ydnv

Connected to Looker version 23.18.60 using Looker API 4.0

============= Validating LookML in project thelook_cicd [warning] ==============

✗ thelook_cicd/business_pulse.dashboard.lookml failed
✗ thelook_cicd/thelook_cicd.model.lkml failed

================ thelook_cicd/business_pulse.dashboard.lookml:28 ===============

[Error] Unknown field "users.state" in explore "users" for field_filter.

LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/business_pulse.dashboard.lookml?line=28

================ thelook_cicd/business_pulse.dashboard.lookml:36 ===============

[Warning] Unknown field "users.state" (for explore "orders" in model
"thelook_cicd") referenced in dashboard element.

LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/business_pulse.dashboard.lookml?line=36

[Additional errors snipped]

Completed validation in 6 seconds.

strumento di convalida dei contenuti

Lo strumento di convalida dei contenuti verifica che i contenuti salvati, come i Look e le dashboard definite dall'utente (UDD) continuino a funzionare anche dopo le modifiche. Per velocizzare l'esecuzione del job e fornire risultati gestibili, la convalida viene eseguita solo per i contenuti basati sulle esplorazioni specificate da te. Lo strumento di convalida dei contenuti ha il seguente nome:

$ spectacles content --config-file config-dev.yaml \
    --project PROJECT_NAME \
    --explores MODEL_NAME/EXPLORE_NAME \
    --branch DEV_BRANCH_NAME

Ad esempio:

$ spectacles content --config-file config-dev.yaml \
    --project thelook_cicd \
    --explores thelook_cicd/users \
    --branch dev-my-user-ydnv

Connected to Looker version 23.18.60 using Looker API 4.0
Building LookML project hierarchy for project 'thelook_cicd' @ dev-my-user-ydnv

==================== Validating content based on 5 explores ====================

✗ thelook_cicd.users failed

================= test dashboard for spectacles [TheLook_CICD] =================

Tile 'test dashboard for spectacles' failed validation.

Error in thelook_cicd/users: Unknown field "users.state".

Dashboard: https://gcpl2318.cloud.looker.com/dashboards/223

========================= Business Pulse [TheLook_CICD] ========================

Filter 'State / Region' failed validation.

Error in thelook_cicd/users: Unknown field "users.state".

Dashboard: https://gcpl2318.cloud.looker.com/dashboards/190

Completed content validation in 27 seconds.

Convalida valore

Convalida di attestare le asserzioni di dati che hai aggiunto a LookML per garantire che i dati vengano letti correttamente. Ad esempio, un test dei dati nel tuo LookML potrebbe avere il seguente aspetto:

test: historic_revenue_is_accurate {
  explore_source: orders {
    column: total_revenue { field: orders.total_revenue }
    filters: [orders.created_date: "2019"]
  }
  assert: revenue_is_expected_value {
    expression: ${orders.total_revenue} = 626000 ;;
  }
}

Il comando della convalida delle affermazioni viene chiamato nel modo seguente:

$ spectacles assert --config-file config-dev.yaml \
    --project PROJECT_NAME \
    --explores MODEL_NAME/EXPLORE_NAME \
    --branch DEV_BRANCH_NAME

Ad esempio:

$ spectacles assert --config-file config-dev.yaml \
    --project thelook_cicd \
    --explores thelook_cicd/users \
    --branch dev-my-user-ydnv

Connected to Looker version 23.18.60 using Looker API 4.0
Building LookML project hierarchy for project 'thelook_cicd' @ dev-my-user-ydnv

==================== Running data tests based on 1 explore =====================

✗ thelook_cicd.users failed

================ thelook_cicd/users/california_users_is_accurate ===============

Unknown filter field "users.state" in lookml test "california_users_is_accurate"
declaration.

LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/thelook_cicd.model.lkml?line=55

================ thelook_cicd/users/california_users_is_accurate ===============

Invalid filter: users.state

LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/thelook_cicd.model.lkml?line=55

================ thelook_cicd/users/california_users_is_accurate ===============

Assertion "count_is_expected_value" failed: expression evaluated to "No".

LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/thelook_cicd.model.lkml?line=55

Completed data test validation in 14 seconds.

Stabilità dei link per Look e dashboard

Per impostazione predefinita, ai Look e alle dashboard vengono assegnati ID numerici in ordine crescente che vengono utilizzati nell'URL del Look o della dashboard. Tuttavia, non è possibile mantenerli sincronizzati tra i sistemi. Di conseguenza, un URL di una dashboard specifica in fase di sviluppo non rimanderà alla stessa dashboard in QA o produzione.

Per i dispositivi UDD è disponibile un'opzione per utilizzare uno slug anziché un ID come parte dell'URL. Lo slug è un insieme semi-casuale di caratteri e non un numero. Lo slug può essere impostato come parte dell'importazione e in modo che un URL simile possa indirizzare allo stesso UDD in fase di sviluppo, QA e produzione. L'utilizzo di slug al posto degli ID è una best practice, in particolare quando si fa clic su un UDD da Look o da un altro UDD.

Per trovare lo slug, esamina l'output di gzr dashboard cat. Al posto dell'ID numerico, è possibile utilizzare lo slug nell'URL della dashboard.

Migrazione dei contenuti degli utenti con Gazer

Spesso è utile copiare contenuti come Look e dashboard tra sviluppo, QA e produzione. Potresti voler produrre contenuti che mostrino nuove aggiunte a LookML o assicurarti che i contenuti salvati funzionino correttamente dopo le modifiche a LookML. In queste situazioni, Gazer può essere utilizzato per copiare contenuti da un'istanza all'altra.

Dashboard LookML

Le dashboard di LookML vengono sincronizzate tra le istanze durante il normale flusso di lavoro CI/CD di LookML. Tuttavia, se eventuali UDD sono sincronizzati con le dashboard LookML, puoi aggiornarle con Gazer utilizzando il seguente comando:

gzr dashboard sync_lookml DASHBOARD_ID --host TARGET_SYSTEM_URL

Dashboard definite dall'utente

Per la migrazione delle dashboard definite dall'utente (UDD) con Gazer, è possibile fare riferimento all'ID della dashboard e all'URL dell'istanza di Looker in cui si trova l'UDD. Gazer salva la configurazione della dashboard in un file JSON che viene poi importato nell'istanza di Looker di destinazione.

Il comando per estrarre la configurazione UDD è il seguente:

gzr dashboard cat DASHBOARD_ID --host TARGET_SYSTEM_URL --dir .

Verrà generato un file denominato Dashboard_DASHBOARD_ID_DASHBOARD_NAME.json contenente la configurazione della dashboard.

L'UDD può essere importato nel sistema di destinazione utilizzando il seguente comando:

gzr dashboard import Dashboard_DASHBOARD_ID_DASHBOARD_NAME.json FOLDER_ID \
    --host TARGET_SYSTEM_URL

Look

La migrazione del Look funziona in modo molto simile alla migrazione UDD. Innanzitutto, utilizza Gazer per salvare la configurazione del Look in un file JSON:

gzr look cat LOOK_ID --host SOURCE_SYSTEM_URL --dir .

Quindi, importa il Look nell'istanza di destinazione:

gzr look import Look_LOOK_ID_LOOK_NAME.json FOLDER_ID \
    --host TARGET_SYSTEM_URL