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

Estensioni per riquadri

A partire da Looker 24.0, le estensioni possono essere sviluppate per essere eseguite in un riquadro delle dashboard. Le estensioni che supportano l'esecuzione come riquadro o visualizzazione possono essere aggiunte mentre la dashboard è in modalità di modifica o salvate in una dashboard come visualizzazione da un'esplorazione. Le estensioni possono anche essere configurate come riquadri nelle dashboard di LookML.

Sono disponibili alcuni esempi di estensioni che possono essere utilizzate come riquadri della dashboard:

L'estensione della visualizzazione riquadro mostra come creare una visualizzazione personalizzata utilizzando il framework dell'estensione.
L'estensione SDK di riquadro mostra i metodi API disponibili specifici per le estensioni dei riquadri.

Utilizzo dell'SDK delle estensioni di Looker con le estensioni dei riquadri

Le estensioni dei riquadri richiedono la definizione del parametro mount_points nel file manifest del progetto LookML per consentire il caricamento delle estensioni come riquadri in una dashboard. Esistono due tipi di mount_points relativi alle estensioni riquadro:

  mount_points: {
    dashboard_vis: yes
    dashboard_tile: yes
    standalone: yes
  }

dashboard_vis: se attivata, l'estensione viene visualizzata nelle opzioni di visualizzazione di un'esplorazione, dove può essere selezionata come visualizzazione e salvata come riquadro della dashboard. Quando la dashboard viene eseguita, esegue la query associata al riquadro e rende i dati disponibili per l'estensione. Il funzionamento è simile a quello delle visualizzazioni personalizzate. La differenza principale tra una visualizzazione personalizzata e un'estensione in esecuzione in un riquadro della dashboard in cui dashboard_vis è abilitato è che l'estensione può effettuare chiamate all'API Looker.
dashboard_tile: se attivata, l'estensione viene mostrata nel riquadro Estensioni visualizzato quando un utente modifica una dashboard e seleziona l'opzione Estensioni dopo aver fatto clic sul pulsante Aggiungi. Questo tipo di estensione è responsabile del recupero dei propri dati, invece di lasciare che la query riquadro fornisca automaticamente i dati all'estensione.

Un ulteriore punto di montaggio, standalone, fa sì che l'estensione venga visualizzata nella sezione Applicazioni del menu principale di Looker. È possibile che un'estensione abbia più punti di montaggio definiti. In fase di runtime, l'estensione riceve una notifica sul modo in cui viene montata e può modificarne il comportamento di conseguenza. Ad esempio, le estensioni standalone potrebbero dover impostare la propria altezza, mentre le estensioni riquadro no.

API aggiuntive per l'estensione Tile

Le estensioni riquadro vengono fornite con API e dati aggiuntivi in fase di runtime. Questi valori sono ottenuti dal contesto dell'estensione:

const {
  tileSDK,
  tileHostData,
  visualizationData,
  visualizationSDK,
} = useContext(ExtensionContext40)

tileSDK: fornisce funzioni specifiche per i riquadri che consentono all'estensione di interagire con l'host della dashboard Looker. Ad esempio, per consentire all'estensione di visualizzare e cancellare i messaggi di errore.
tileHostData: fornisce dati del riquadro all'estensione. I dati vengono aggiornati automaticamente in base alle interazioni con la dashboard di hosting. Un esempio è l'indicatore isDashboardEditing.
visualizationSDK: fornisce funzioni specifiche per la visualizzazione per consentire all'estensione di interagire con l'host della dashboard Looker. Un esempio è la funzione updateRowLimit.
visualizationData: fornisce dati di visualizzazione all'estensione. I dati vengono aggiornati automaticamente in base alle interazioni con la dashboard di hosting. I dati sono simili a quelli forniti alle visualizzazioni personalizzate.

Sviluppo di estensioni reattive

Gli iframe in cui vengono eseguite le estensioni vengono ridimensionati automaticamente quando viene ridimensionata la finestra host di Looker principale. Questo si riflette automaticamente nella finestra dei contenuti iframe. Il componente iframe non ha spaziatura interna o margine, quindi è compito dell'estensione fornire la propria spaziatura interna e il proprio margine in modo che sembri coerente con l'applicazione Looker. Per le estensioni indipendenti, è l'estensione a controllarne l'altezza. Per le estensioni che vengono eseguite nei riquadri della dashboard o nelle visualizzazioni Esplora, la finestra dei contenuti dell'iframe verrà impostata automaticamente sull'altezza resa disponibile dall'iframe.

Considerazioni sul rendering

È importante notare che le estensioni riquadro verranno visualizzate quando una dashboard viene scaricata come PDF o immagine. Il renderer prevede che il riquadro lo invii una notifica al termine del rendering. In caso contrario, il renderer smetterà di rispondere. Di seguito è riportato un esempio di come notificare al renderer l'esecuzione del rendering del riquadro.

  const { extensionSDK } = useContext(ExtensionContext40)

  useEffect(() => {
    extensionSDK.rendered()
  }, [])

Le animazioni dovrebbero essere disattivate anche durante il rendering. Di seguito è riportato un esempio in cui le configurazioni dell'animazione sono disattivate durante il rendering:

  const { lookerHostData} = useContext(ExtensionContext40)
  const isRendering = lookerHostData?.isRendering

  const config = isRendering
    ? {
        ...visConfig,
        valueCountUp: false,
        waveAnimateTime: 0,
        waveRiseTime: 0,
        waveAnimate: false,
        waveRise: false,
      }
    : visConfig

  if (mountPoint === MountPoint.dashboardVisualization) {
    return <VisualizationTile config={config} />
  }

Funzioni e proprietà dell'SDK Tile

L'SDK dei riquadri fornisce funzioni che consentono a un'estensione riquadro di interagire con la dashboard di hosting.

Le funzioni e le proprietà disponibili sono mostrate nella tabella seguente:

Funzione o proprietà	Descrizione
`tileHostData` (proprietà)	Ospita dati specifici per l'estensione riquadro. Consulta la sezione Dati dell'SDK Tile per dettagli.
`addError`	Quando chiamata, la dashboard o l'esplorazione mostrerà un messaggio di errore sotto la visualizzazione.
`clearError`	Quando viene richiamata, la dashboard o l'esplorazione nasconde qualsiasi messaggio di errore mostrato sotto la visualizzazione.
`openDrillMenu`	Per le estensioni di visualizzazione, questa chiamata apre un menu drill. Questa chiamata viene ignorata se l'estensione non è una visualizzazione di estensione riquadro.
`runDashboard`	Esegue la dashboard attuale. Questa chiamata è ignorata da un'estensione di visualizzazione riquadri in esecuzione in un'esplorazione.
`stopDashboard`	Arresta una dashboard in esecuzione. Questa chiamata è ignorata da un'estensione di visualizzazione riquadri in esecuzione in un'esplorazione.
`updateFilters`	Aggiorna i filtri nella dashboard corrente o in Esplora.
`openScheduleDialog`	Apre la finestra di dialogo di pianificazione. Questa chiamata viene ignorata se viene eseguita in un'esplorazione.
`toggleCrossFilter`	Attiva/disattiva i filtri incrociati. Questa chiamata viene ignorata se viene eseguita in un'esplorazione.

Dati dell'SDK Tile

Le proprietà dei dati dell'SDK dei riquadri disponibili sono mostrate nella tabella seguente:

Proprietà	Descrizione
`isExploring`	Se true, indica che il riquadro è in fase di configurazione come visualizzazione all'interno di un'esplorazione.
`dashboardId`	L'ID della dashboard del riquadro di cui viene eseguito il rendering. Se il riquadro è configurato come esplorazione, questa proprietà non verrà compilata.
`elementId`	L'ID elemento del riquadro di cui viene eseguito il rendering. Se il riquadro è configurato come esplorazione, questa proprietà non verrà compilata.
`queryId`	L'ID query del riquadro di cui viene eseguito il rendering se associato a una visualizzazione. Se il riquadro è configurato come esplorazione, questa proprietà non verrà compilata. `queryId` è l'ID della query creata quando la visualizzazione è integrata nell'esplorazione di Looker. Non contiene filtri o filtri incrociati da applicare alla dashboard. Per riflettere i dati mostrati in `QueryResponse`, sarà necessario applicare filtri e filtri incrociati e generare una nuova query. Di conseguenza, le proprietà potrebbero essere più utili rispetto a `queryId`. Vedi `filteredQuery` per un oggetto di query con filtri applicati.
`querySlug`	Lo slug della query del riquadro di cui viene eseguito il rendering se è associato a una visualizzazione. Se il riquadro è configurato come esplorazione, questa proprietà non verrà compilata. `querySlug` è uno slug della query che viene creata quando la visualizzazione è integrata nell'esplorazione di Looker. Non contiene filtri o filtri incrociati applicati alla dashboard. Per riflettere i dati mostrati in `QueryResponse`, sarà necessario applicare filtri e filtri incrociati e generare una nuova query. Di conseguenza, le proprietà potrebbero essere più utili rispetto a `querySlug`. Vedi `filteredQuery` per un oggetto di query con filtri applicati.
`dashboardFilters`	I filtri applicati alla dashboard. Se il riquadro è configurato come esplorazione, questa proprietà non verrà compilata.
`dashboardRunState`	Indica se la dashboard è in esecuzione. Se il riquadro viene configurato come esplorazione, lo stato sarà `UNKNOWN`. Per motivi legati alle prestazioni della dashboard, il runstate potrebbe non essere mai visualizzato come in esecuzione. In genere questo accade se non ci sono altri riquadri associati a una query, incluso quello a cui è associata l'estensione. Se l'estensione deve sapere con certezza che una dashboard è stata eseguita, il rilevamento delle differenze in `lastRunStartTime` è il modo affidabile.
`isDashboardEditing`	Se il valore è true, la dashboard è in fase di modifica. Se il riquadro è configurato come esplorazione, questa proprietà non verrà compilata.
`isDashboardCrossFilteringEnabled`	Se il valore è true, il filtro incrociato è attivato nella dashboard. Se il riquadro è configurato come esplorazione, questa proprietà non verrà compilata.
`filteredQuery`	Un oggetto query che corrisponde all'ID query associato all'elemento sottostante della dashboard che applica eventuali filtri della dashboard e modifiche al fuso orario effettuati a livello di dashboard.
`lastRunSourceElementId`	L'ID dell'elemento dell'estensione riquadro che ha attivato l'ultima esecuzione della dashboard. L'ID non è definito se l'esecuzione della dashboard è stata attivata dal pulsante Esegui o dall'aggiornamento automatico della dashboard oppure se è stata attivata utilizzando l'SDK incorporato. Se il riquadro è configurato come esplorazione, questa proprietà non verrà compilata. Tieni presente che `lastRunSourceElementId` può essere uguale all'ID elemento dell'istanza dell'estensione corrente. Ad esempio, se l'estensione attiva un'esecuzione della dashboard, questa riceverà una notifica quando l'esecuzione della dashboard inizia e termina.
`lastRunStartTime`	Indica l'ora di inizio dell'ultima esecuzione della dashboard. Se il riquadro è configurato come esplorazione, questa proprietà non verrà compilata. Tieni presente che le ore di inizio e di fine indicate non devono essere utilizzate per acquisire le metriche sul rendimento.
`lastRunEndTime`	Indica l'ora di fine dell'ultima esecuzione della dashboard. Se il riquadro è configurato come esplorazione, questa proprietà non verrà compilata. Se il riquadro è in esecuzione, questa proprietà non verrà compilata. Tieni presente che le ore di inizio e di fine indicate non devono essere utilizzate per acquisire le metriche sul rendimento.
`lastRunSuccess`	Indica se l'ultima esecuzione della dashboard è riuscita o meno. Se il riquadro è configurato come esplorazione, questa proprietà non verrà compilata. Se il riquadro è in esecuzione, questa proprietà non verrà compilata.

Funzioni e proprietà dell'SDK di visualizzazione

Le funzioni e le proprietà dell'SDK di visualizzazione disponibili sono indicate nella seguente tabella:

Funzione o proprietà	Descrizione
`visualizationData` (proprietà)	Visualizzazione (combinazione di dati di `visConfig` e `queryResponse`).
`visConfig` (proprietà)	Dati di configurazione di visualizzazione: Configurazioni di misurazione Configurazioni delle dimensioni Calcoli tabulari Configurazioni pivot Configurazioni di visualizzazione che vengono utilizzati per personalizzare l'aspetto di una visualizzazione in un'esplorazione.
`queryResponse` (proprietà)	Dati di risposta dalla query
`configureVisualization`	Consente di impostare la configurazione predefinita per una visualizzazione di estensioni. La configurazione verrà visualizzata all'interno dell'editor di visualizzazione Esplora. Deve essere chiamato una sola volta.
`setVisConfig`	Aggiorna la configurazione di visualizzazione.
`updateRowLimit`	Aggiorna il limite di righe di query.

Dati dell'SDK di visualizzazione

L'SDK di visualizzazione è costituito dai seguenti elementi:

Dati di configurazione di visualizzazione
Dati delle risposte alle query

Dati di configurazione di visualizzazione

Proprietà	Descrizione
`queryFieldMeasures`	Informazioni sulla misurazione
`queryFieldDimensions`	Informazioni sulle dimensioni
`queryFieldTableCalculations`	Informazioni sul calcolo tabulare
`queryFieldPivots`	Informazioni pivot
`visConfig`	Dati di configurazione visivi. Deve essere unita alla configurazione predefinita e applicata alla visualizzazione visualizzata dall'estensione.

export interface VisualizationConfig {
  queryFieldMeasures: Measure[]
  queryFieldDimensions: Dimension[]
  queryFieldTableCalculations: TableCalculation[]
  queryFieldPivots: PivotConfig[]
  visConfig: RawVisConfig
}

Dati delle risposte alle query

Proprietà	Descrizione
`data`	Array di dati di riga
`fieldMeasures`	Informazioni sulla misurazione di campo.
`fieldDimensions`	Informazioni sulla dimensione del campo.
`fieldTableCalculations`	Informazioni sui calcoli della tabella dei campi.
`fieldPivots`	Informazioni sul pivot del campo.
`fieldMeasureLike`	Un array concatenato di informazioni sulle misure di campo e calcoli tabulari che si comportano come misure.
`fieldDimensionLike`	Un array concatenato di informazioni sulle dimensioni dei campi e calcoli tabulari che si comportano come dimensioni.