Sviluppo di un blocco personalizzato per Looker Marketplace

In questa pagina viene descritto come creare un blocco personalizzato che può essere aggiunto a Looker Marketplace e a cui possono accedere altri utenti di Looker.

Tieni presente che devi essere un membro della rete di partner Looker o un cliente Looker per inviare contenuti a Looker Marketplace.

Per informazioni sui Looker Blocks già creati e disponibili per l'uso, consulta la pagina della documentazione relativa ai blocchi di Looker. Per informazioni sulla personalizzazione dei blocchi installati dal Marketplace, consulta la pagina della documentazione Personalizzazione dei blocchi di Looker Marketplace.

Per sviluppare un blocco e renderlo disponibile a tutti gli utenti Looker tramite Looker Marketplace, segui i passaggi descritti in questa pagina:

  1. Configurare e connettere l'origine dati a Looker.
  2. Crea un progetto e aggiungi i file richiesti.
  3. Rendi il blocco accessibile.
  4. Invia il blocco per la revisione di Looker.

Configurare e connettere l'origine dati a Looker.

I blocchi sono modelli di dati, quindi funzionano meglio quando sono progettati per un set di dati specifico e facilmente ripetibile. La maggior parte degli errori di installazione di blocchi si verifica quando il set di dati dell'utente non corrisponde ai nomi di schema, tabella e campo nel blocco.

  • Se stai creando un blocco per un set di dati specifico, come i dati di Google Analytics, prendi nota delle impostazioni o delle personalizzazioni apportate al set di dati. Quando possibile, mantieni al minimo queste personalizzazioni per semplificare l'installazione per gli utenti. Fornisci istruzioni specifiche in un file README.
  • Se stai creando un blocco per un pattern di analisi generale, come la conservazione delle coorti, prendi nota dei campi che prevedi che il set di dati dell'utente contenga. Molto probabilmente, gli utenti non avranno lo stesso nome di schema, tabella e campo del tuo set di dati. Utilizza le costanti LookML per i nomi delle tabelle e dei campi e comunica all'utente quali campi devono essere aggiornati in un file README.

Una volta stabilita l'origine dati, connettila a Looker in modo da poter iniziare a creare i modelli. Se devi modificare una qualsiasi delle impostazioni di connessione predefinite, prendi nota del file README.

Creazione di un progetto e aggiunta dei file richiesti

Crea un progetto per rappresentare il blocco. Prendi in considerazione una convenzione di denominazione come
block-<database_dialect>-<role> (ad esempio, block-redshift-admin).

Quindi, crea i seguenti file nel tuo progetto:

  • Un file manifest che definisce il nome del progetto, il nome della connessione e qualsiasi altra costante.
  • Un file vista per ogni vista
  • Un file Explore per ogni Explore
  • Un file modello che include tutti i file delle viste, i file di esplorazione e i file della dashboard di LookML nel progetto
  • Almeno tre file della dashboard LookML
  • Un file marketplace.json contenente le informazioni che verranno visualizzate nella scheda del Marketplace per questo blocco
  • Un file LICENSE che include il testo della licenza open source MIT
  • Un file README con istruzioni e opzioni di configurazione

Gli utenti che installano il blocco possono perfezionare la base Esplora, visualizzazioni e dashboard in un refinements.lkml file separato. Nelle sezioni che seguono vengono descritti in dettaglio i singoli tipi di file richiesti:

Creazione di un file manifest

Crea un file manifest per il tuo progetto. Il file manifest deve iniziare con un nome di progetto e poi definire alcune costanti LookML che gli utenti possono modificare. Ad esempio, devi definire il nome della connessione Looker come una costante con export: override_required, in modo che gli utenti possano sostituirla con il nome della connessione.

Di seguito è riportato un file manifest di esempio:

project_name: "block-ga-360"

################# Constants ################

## Used in google_analytics_block.model connection param
constant: CONNECTION_NAME {
  value: "looker-private-demo"
  export: override_required
}

## Used in ga_sessions.view sql_table_name
constant: SCHEMA_NAME {
  value: "bigquery-public-data.google_analytics_sample"
  export: override_optional
}

constant: GA360_TABLE_NAME {
  value: "ga_sessions_*"
  export: override_optional
}

Creazione di file di visualizzazione ed esplorazione

Crea un file view.lkml per ogni vista. Se i nomi di schema e tabella di un utente potrebbero differire dal tuo, assicurati di definire i nomi di schema e tabella come costanti nel tuo file manifest in modo che gli utenti che scaricano il blocco possano aggiornare i nomi di schema e tabella nel file manifest generato automaticamente. Successivamente, fai riferimento a queste costanti nei parametri sql_table_name delle viste.

Ecco un esempio di file di blocco view.lkml:

view: user_facts {

  # SCHEMA_NAME and GA360_TABLE_NAME are constants
  sql_table_name: @{SCHEMA_NAME}.@{GA360_TABLE_NAME} ;;

  dimension: clientID {
    type: string
    sql: ${TABLE.clientId}
  }

}

Quindi, crea uno o più file explore.lkml. Assicurati che ogni file di esplorazione includa le viste necessarie per l'esplorazione. Progetta le tue esplorazioni con attenzione, in modo che contengano join logici, esercitazioni e pagine curate di Explore. Dopo che un altro utente ha installato il blocco dal Marketplace, dovrebbe essere semplice per gli utenti aziendali entrare e iniziare ad analizzare i propri dati.

Puoi trovare un elenco generale delle best practice per la definizione del modello sul nostro forum della community e nelle best practice di Looker, ad esempio Best practice: cosa fare e cosa non fare e Best practice: scrittura di LookML sostenibili e gestibili.

Ecco un esempio di file explore.lkml:

include: "/Google_Analytics/Sessions/*.view.lkml"

explore: future_input {
  view_label: "Audience Traits"
  label: "BigQuery ML Customer Likelihood to Purchase"

  join: future_purchase_prediction {
    type: left_outer
    sql_on: ${future_purchase_prediction.clientId} = ${future_input.client_id} ;;
    relationship: one_to_one
  }
}

Creazione di un file del modello

Crea un file modello che includa tutti i file delle visualizzazioni, delle esplorazioni e della dashboard nel tuo progetto. Assicurati che nel file manifest sia fatto riferimento al nome della connessione come costante LookML.

Definisci almeno un datagroup per impostare un criterio di memorizzazione nella cache.

Ecco un esempio di file di modello:

connection: "@{CONNECTION_NAME}"

include: "/views/*.view.lkml"
include: "/explores/*.explore.lkml"
include: "/dashboards/*.dashboard.lookml"

datagroup: nightly {
  sql_trigger: SELECT TIMEZONE('US/Pacific',GETDATE())::DATE;;
}

Creazione di file di dashboard LookML

Per essere inclusi in Looker Marketplace, ogni blocco deve includere almeno tre dashboard LookML che forniscano analisi utili e significative. Le dashboard devono essere estetiche, funzionali e complete e non devono presentare dati sfocati.

Anche se non sono previsti requisiti di progettazione rigidi per le dashboard di LookML, Looker consiglia queste best practice generali di progettazione:

  • Tavolozza dei colori coerente su tutto il pannello
  • Almeno sette riquadri
  • Un minimo di tre diversi tipi di visualizzazione (ad esempio, valore singolo, barra e riga)

Le visualizzazioni personalizzate non sono supportate durante lo sviluppo delle dashboard per i blocchi. Utilizza invece i tipi di visualizzazione nativi di Looker.

Per ulteriori informazioni sulla personalizzazione delle dashboard di LookML e sulle visualizzazioni all'interno delle dashboard di LookML, consulta le pagine della documentazione relative ai parametri della dashboard e ai parametri degli elementi della dashboard. Per un esempio di un file di dashboard LookML, consulta il file della dashboard di Lookshift per l'amministratore di Redshift del blocco dell'amministratore di Redshift.

Creazione di un file marketplace.json in corso...

Crea un file marketplace.json per fornire informazioni sulla visualizzazione della scheda nel Marketplace. Ogni blocco in Looker Marketplace deve fornire queste informazioni aggiuntive per aiutare gli utenti a selezionare il blocco più adatto alle proprie esigenze. Il file marketplace.json deve contenere:

  • Campi Marketplace label, category_label e branding
  • Un elenco di costanti LookML che gli utenti devono compilare per completare il modello LookML (ad esempio, i nomi delle connessioni)

Ecco un esempio di file marketplace.json per il blocco del rendimento di Google BigQuery:

{
  "label": "Google BigQuery Performance",
  "category_label": "Models",
  "branding": {
    "image_uri": "https://marketplace-api.looker.com/block-icons/google-cloud.png",
    "tagline": "This Block provides a comprehensive overview of all cost and performance data for one or multiple BigQuery projects, enabling users to effectively monitor BigQuery usage down to a per user level. It can be used to set up alerts to long running or high cost queries."
  },

  "constants": {
    "CONNECTION_NAME": {
      "label": "Connection Name",
      "value_constraint": "connection"
    },
    "SCHEMA_NAME": {
      "label": "Schema Name"
    },
    "AUDIT_LOG_EXPORT_TABLE_NAME": {
      "label": "Audit Log Export Table Name",
      "description": "The table name of your BigQuery Optimization data (typically cloudaudit_googleapis_com_data_access_*)."
    }
  },
  "models": [
    {
      "name": "block_bigquery_optimization_v2",
      "connection_constant": "CONNECTION_NAME"
    }
  ]
}

Il seguente screenshot mostra la scheda del Marketplace generata da questo file marketplace.json.

Un esempio di scheda del Marketplace.

  • Il campo "label" controlla il titolo del blocco. In questo esempio, si tratta di Google BigQuery Performance.
  • Il campo "tagline" controlla il primo paragrafo della scheda Marketplace.
  • Il campo "image_uri" controlla l'immagine mostrata nell'angolo in alto a sinistra della scheda Marketplace. In questo esempio è il logo di Google Cloud.
  • Il campo "constants" chiede agli utenti di completare le costanti nell'interfaccia utente di Marketplace durante la procedura di installazione. In questo esempio, nel file marketplace.json (CONNECTION_NAME, SCHEMA_NAME e AUDIT_LOG_EXPORT_TABLE_NAME sono elencate tre costanti), quindi all'utente verrà chiesto di specificare i valori dei tre campi prima di eseguire l'installazione.

Creazione di un file LICENSE

Tutti i Looker Blocks devono essere in possesso della licenza MIT open source. Includi il testo di questa licenza in un file denominato LICENSE. Per un esempio di file LICENZA, consulta il file Redshift Admin LICENSE.

Creazione di un file README

Il file README deve contenere tutte le istruzioni per l'implementazione del blocco e deve identificare esplicitamente dove sono necessarie eventuali personalizzazioni, ad esempio nel file manifest generato automaticamente](#the_autogenerate_manifest_file) o nel file di perfezionamento. Per un esempio di un file README, consulta il file README del blocco amministrativo Redshift.

Aspetti da considerare per il tuo README:

  • Di quale origine dati ha bisogno l'utente? L'utente deve pagare un abbonamento?
  • Quali autorizzazioni deve avere l'utente del database?
  • Quali impostazioni di connessione Looker sono necessarie?
  • I nomi dei campi bloccati corrispondono ai nomi dei campi contenuti nel set di dati dell'utente? In caso contrario, cosa deve cambiare l'utente?

File generati automaticamente

Quando gli utenti installano il blocco, la loro istanza di Looker crea un nuovo progetto Looker con i file del progetto come file di sola lettura. Inoltre, l'utente genererà automaticamente i seguenti file:

  • Un file marketplace_lock.lkml di sola lettura contenente informazioni sulla scheda del marketplace
  • Un file manifest che fa riferimento alla scheda da marketplace_lock.lkml
  • Un file refinements.lkml che include tutte le visualizzazioni e le esplorazioni del blocco
  • Un file modello di sola lettura che includa sia il file del modello del tuo blocco sia il file refinements.lkml

Gli utenti che installano il blocco da Looker Marketplace possono utilizzare il file refinements.lkml per perfezionare il tuo LookML e persino aggiungere nuovi file LookML. Per ulteriori informazioni su come gli utenti possono personalizzare il blocco, consulta la pagina della documentazione relativa alla personalizzazione dei blocchi di Looker Marketplace.

Il file manifest generato automaticamente

Il file manifest generato automaticamente consente agli utenti che installano il blocco di impostare variabili come il nome della connessione. Le costanti LookML definite nel file manifest di blocco possono essere modificate nel file manifest generato automaticamente o impostate dagli utenti nell'interfaccia di download a blocchi.

Il file dei perfezionamenti

Il file refinements.lkml generato automaticamente consente agli utenti che installano il blocco di perfezionare le visualizzazioni e le esplorazioni che sono definite del blocco. È qui che gli utenti che scaricano il blocco eseguono la maggior parte della personalizzazione di LookML per adattarli al proprio caso d'uso.

Ecco un esempio di un file refinements.lkml generato automaticamente:

include: "//ga360-v2/**/*.view.lkml"
include: "//ga360-v2/**/*.explore.lkml"

\# Use LookML refinements to refine views and explores that are defined in the remote project.
\# Learn more at: https://docs.looker.com/data-modeling/learning-lookml/refinements
\#
\#
\# For example we could add a new dimension to a view:
\#     view: +flights {
\#       dimension: air_carrier {
\#         type: string
\#         sql: ${TABLE}.air_carrier ;;
\#       }
\#     }
\#
\# Or apply a label to an explore:
\#     explore: +aircraft {
\#       label: "Aircraft Simplified"
\#     }
\#

Rendere accessibile il progetto a blocchi

Ospita il tuo blocco LookML su un repository GitHub accessibile pubblicamente.

Tutti i blocchi Looker devono avere una licenza MIT open source e il testo della licenza deve essere incluso in un file LICENZA nel repository.

Inviare il blocco per la revisione

Quando il blocco è pronto per l'invio, segui le istruzioni riportate nell'articolo sull'invio di contenuti a Looker Marketplace per creare la documentazione di supporto per il blocco, invia il blocco al team Looker per la revisione e pubblica il blocco in Looker Marketplace.