Sviluppo di un blocco personalizzato per il marketplace di Looker

Questa pagina descrive come creare un blocco personalizzato che può essere aggiunto a Looker Marketplace e a cui possono accedere altri utenti di Looker.

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

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

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

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

Configurazione e connessione dell'origine dati a Looker

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

  • Se stai creando un blocco per un set di dati specifico, ad esempio i dati di Google Analytics, prendi nota di eventuali impostazioni o personalizzazioni apportate al set di dati. Se possibile, riduci 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 fidelizzazione delle coorti, prendi nota dei campi che prevedi che il set di dati dell'utente contenga. Molto probabilmente, gli utenti non avranno gli stessi nomi di schema, tabella e campo del tuo set di dati. Utilizza le costanti LookML per i nomi di tabelle e campi e comunica all'utente quali campi deve aggiornare in un file README.

Una volta determinata l'origine dati, collega l'origine dati a Looker per iniziare la modellazione. Se devi modificare le impostazioni di connessione predefinite, prendi nota nel file README.

Creare un progetto e aggiungere i file richiesti

Crea un progetto per rappresentare il tuo blocco. Valuta la possibilità di utilizzare una convenzione di denominazione come block-<database_dialect>-<role> (ad esempio block-redshift-admin).

Poi create i seguenti file nel progetto:

  • Un file manifest che definisce il nome del progetto, il nome della connessione e eventuali altre costanti
  • Un file di visualizzazione per ogni visualizzazione
  • Un file di esplorazione per ogni esplorazione
  • Un file modello che include tutti i file di vista, di esplorazione e di dashboard LookML del progetto
  • Almeno tre file 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 che descrive le istruzioni e le opzioni di configurazione

Gli utenti che installano il tuo blocco possono affinare le esplorazioni, le visualizzazioni e le dashboard di base in un refinements.lkmlfile separato. Le sezioni seguenti spiegano in modo più dettagliato ogni tipo di file richiesto:

Creazione di un file manifest

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

Ecco 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 visualizzazioni ed esplorazioni

Crea un file view.lkml per ogni visualizzazione. Se i nomi dello schema e delle tabelle di un utente potrebbero essere diversi dai tuoi, assicurati di definirli come costanti nel file manifest in modo che gli utenti che scaricano il tuo blocco possano aggiornarli nel file manifest generato automaticamente. Poi fai riferimento a queste costanti nei parametri sql_table_name delle tue visualizzazioni.

Ecco un esempio di file view.lkml del blocco:

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}
  }

}

Poi, crea uno o più file explore.lkml. Assicurati che ogni file di esplorazione includa le visualizzazioni necessarie per l'esplorazione. Progetta le esplorazioni in modo attento in modo che contengano unioni logiche, drill-down e pagine di esplorazione selezionate. Dopo che un altro utente ha installato il blocco dal marketplace, gli utenti aziendali dovrebbero poter iniziare facilmente ad analizzare i dati.

Puoi trovare un elenco generale delle best practice per la definizione dei modelli nel nostro forum della community e nelle best practice di Looker, ad esempio Best practice: cosa fare e cosa non fare con LookML e Best practice: scrivere LookML sostenibile e manutenibile.

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"
  description: "This explore allows you to slice and dice likeliness to purchase scores by different customer traits to see how they differ. The default range of data you are looking at is in the past 30 days"
  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 del modello che includa tutti i file di visualizzazioni, esplorazioni e dashboard del progetto. Assicurati che al nome della connessione sia fatto riferimento come a una costante LookML dal file manifest.

Definisci almeno un gruppo di dati per impostare un criterio di memorizzazione nella cache.

Ecco un esempio di file del 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 incluso in Looker Marketplace, ogni blocco deve includere almeno tre dashboard LookML che forniscono analisi significative e utili. Le dashboard devono essere estetiche, funzionali e complete e non devono includere dati sfocati.

Sebbene non siano previsti requisiti di progettazione rigidi per le dashboard di LookML, Looker consiglia queste best practice generali di progettazione:

  • Tavolozza dei colori coerente in tutta la dashboard
  • Almeno sette riquadri
  • Almeno tre tipi di visualizzazione diversi (ad es. a un solo valore, a barre e a linee)

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

Per ulteriori informazioni sulla personalizzazione delle dashboard e delle visualizzazioni all'interno delle dashboard di LookML, consulta le pagine di documentazione relative ai parametri della dashboard e ai parametri degli elementi della dashboard. Per un esempio di file della dashboard di LookML, consulta il file della dashboard di LookML di Redshift Admin nel blocco Redshift Admin.

Creazione di un file marketplace.json

Crea un file marketplace.json per fornire informazioni su come deve essere visualizzata la scheda nel marketplace. Ogni blocco in Looker Marketplace deve fornire queste informazioni aggiuntive per aiutare gli utenti a selezionare il blocco più adatto alle loro esigenze. Il file marketplace.json deve contenere:

  • Campi Marketplace label, category_label e branding
  • Un elenco di costanti LookML che dovranno essere compilate dagli utenti per completare il modello LookML (ad es. i nomi delle connessioni)

Ecco un esempio di file marketplace.json per il blocco 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"
    }
  ]
}

Lo screenshot seguente mostra la scheda del marketplace che verrebbe generata da questo file marketplace.json.

Una scheda di Marketplace di esempio.

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

Creazione di un file LICENSE

Tutti i blocchi di Looker devono essere concessi in licenza ai sensi della licenza open source MIT. Includi il testo di questa licenza in un file denominato LICENSE. Per un esempio di file LICENSE, consulta il file LICENSE del blocco di amministrazione Redshift.

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_autogenerated_manifest_file) o nel file di perfezionamento. Consulta il file README del blocco di amministrazione Redshift per un esempio di file README.

Aspetti da considerare per il file README:

  • Di quale origine dati ha bisogno l'utente? Devono pagare un abbonamento?
  • Quali autorizzazioni deve avere l'utente del database?
  • Quali impostazioni di connessione di Looker sono necessarie?
  • I nomi dei campi del blocco corrisponderanno a quelli del set di dati dell'utente? In caso contrario, cosa deve cambiare l'utente?

File generati automaticamente

Quando gli utenti installano il tuo blocco, la loro istanza di Looker crea un nuovo progetto Looker con i file del tuo progetto come file di sola lettura. Verranno inoltre generati automaticamente i seguenti file per l'utente:

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

Gli utenti che installano il tuo blocco dal marketplace di Looker possono utilizzare il file refinements.lkml per affinare il tuo LookML e persino aggiungere nuovi file LookML. Per ulteriori informazioni su come gli utenti possono personalizzare il tuo blocco, consulta la pagina della documentazione 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 del blocco possono essere modificate nel file manifest generato automaticamente o impostate dagli utenti nell'interfaccia utente del download del blocco.

Il file di perfezionamento

Il file refinements.lkml generato automaticamente consente agli utenti che installano il tuo blocco di affinare le visualizzazioni e le esplorazioni che lo definiscono. Qui gli utenti che scaricano il tuo blocco eseguono la maggior parte della personalizzazione di LookML in base al loro caso d'uso.

Ecco un esempio di 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 di blocco

Ospitata il tuo blocco LookML in un repository GitHub accessibile al pubblico.

Tutti i blocchi di Looker devono essere concessi in licenza ai sensi della licenza open source MIT e il testo della licenza deve essere incluso in un file LICENSE nel repository.

Invio del blocco per la revisione

Una volta che il blocco è pronto per essere inviato, segui le istruzioni riportate in Invio di contenuti a Looker Marketplace per creare la documentazione di supporto per il blocco, inviarlo al team di Looker per la revisione e pubblicarlo su Looker Marketplace.