Risoluzione dei problemi relativi al framework di estensione Looker

Il framework di estensione di Looker ti consente di creare applicazioni e visualizzazioni JavaScript e TypeScript personalizzate che vengono eseguite all'interno di Looker. Le estensioni vengono eseguite in un iframe in modalità sandbox e interagiscono con l'istanza di Looker tramite l'SDK Extension. Se riscontri problemi con un'estensione personalizzata, ad esempio una pagina vuota o un messaggio di errore all'interno di iframe, errori JavaScript della console del browser o di condivisione delle risorse tra origini (CORS), richieste API di Looker non riuscite (codici di stato 4xx o 5xx) o errori di configurazione di manifest.lkml, questo documento ti aiuta a risolverli.

Prerequisiti e requisiti di configurazione comuni

Prima di iniziare la risoluzione dei problemi, verifica che l'ambiente, il progetto LookML e l'account utente soddisfino i requisiti per l'esecuzione di un'estensione di Looker:

  • Framework di estensione abilitato: un amministratore di Looker deve abilitare l'impostazione Framework di estensione in Amministrazione > Piattaforma > Framework di estensione.
  • Configurazione del progetto e del modello LookML: ogni estensione richiede un progetto LookML che includa i seguenti componenti:
  • Autorizzazioni del manifest: la dichiarazione application nel file manifest.lkml deve definire esplicitamente tutti i entitlements richiesti dall'estensione, ad esempio core_api_methods per le chiamate API di Looker o external_api_urls per le richieste a domini esterni. Un'estensione non verrà eseguita senza un blocco entitlements.
  • Autorizzazioni utente: gli utenti devono disporre delle autorizzazioni per le estensioni (ad esempio access_data, explore o develop) per un set di modelli che include il modello LookML dell'estensione. Per creare un'estensione, gli sviluppatori devono disporre delle autorizzazioni LookML develop.
  • Strumenti diagnostici e dettagli dell'ambiente: prima di iniziare la risoluzione dei problemi, prepara i seguenti dettagli e strumenti:
    • L'URL dell'istanza di Looker, il nome del progetto LookML e il nome di application dichiarato in manifest.lkml.
    • Accesso agli strumenti per sviluppatori del browser web (schede Console e Rete) sul computer client.
    • Durante lo sviluppo locale, l'accesso al terminale che esegue il server di sviluppo locale.
    • Per gli errori del server 5xx nelle chiamate API Looker, l'accesso ai log dell'istanza di Looker (looker.log nelle istanze ospitate dal cliente o Esplora log in Cloud Logging nella console Google Cloud per le istanze di Looker (Google Cloud core)).

Albero di debug

Utilizza il seguente albero decisionale per iniziare a risolvere i problemi del framework di estensione Looker:

Le sezioni seguenti descrivono in modo più dettagliato gli scenari nell'albero.

Ispeziona i log della console e i log di rete del browser

Poiché le estensioni di Looker vengono eseguite lato client nel browser, inizia la risoluzione dei problemi esaminando gli strumenti per sviluppatori del browser per verificare la presenza di errori JavaScript, violazioni delle policy di sicurezza e richieste HTTP non riuscite.

Controlla la console del browser per verificare la presenza di errori

Per identificare gli errori lato client che impediscono il caricamento o l'esecuzione dell'estensione:

  1. In Looker, apri la pagina in cui viene caricata l'estensione.
  2. Fai clic con il tasto destro del mouse su un punto qualsiasi della pagina e seleziona Ispeziona (o premi Ctrl+Shift+I su Windows e Linux o Cmd+Opzione+I su macOS).
  3. Nel riquadro degli strumenti per sviluppatori, seleziona la scheda Console.
  4. Aggiorna la pagina per acquisire gli errori che si verificano durante il caricamento iniziale.
  5. Controlla eventuali messaggi di errore rossi nella console:

Controlla la scheda Rete per individuare le richieste non riuscite

Per analizzare le richieste HTTP effettuate dall'estensione per bundle JavaScript, asset o endpoint API, segui questi passaggi:

  1. Nel riquadro degli strumenti per sviluppatori del browser, seleziona la scheda Rete.
  2. Seleziona la casella di controllo Disattiva cache in modo che il browser non carichi risorse memorizzate nella cache obsolete.
  3. Aggiorna la pagina in cui viene caricata l'estensione.
  4. Controlla l'elenco delle richieste di rete per individuare eventuali codici di stato 4xx o 5xx e seleziona una richiesta non riuscita per esaminare le schede Intestazioni, Payload e Risposta:
    • 404 sul bundle di estensioni (ad esempio bundle.js): verifica che il server di sviluppo sia in esecuzione e che il parametro url o file in manifest.lkml sia corretto.
    • 401 o 403 su una richiesta API Looker: esamina autenticazione, autorizzazioni e diritti.
    • 400 o 422 su una richiesta API: esamina le schede Payload e Risposta per identificare JSON non corretti o parametri di richiesta non validi.
    • Errori del server 5xx: indicano errori lato server nell'istanza Looker. Controlla looker.log nelle istanze ospitate dal cliente o Esplora log nella console per le istanze di Looker (Google Cloud core) per trovare voci con timestamp corrispondenti.

Se non vengono visualizzati errori nelle schede Console o Rete o se devi verificare in che modo Looker carica l'estensione, vai alla sezione successiva.

Verifica il manifest e la configurazione del progetto

La dichiarazione application nel file manifest.lkml del tuo progetto controlla il modo in cui Looker carica l'estensione e le risorse che l'estensione può utilizzare. Le configurazioni errate in manifest.lkml sono una causa comune di errori di caricamento e dell'API:

  • Verifica il parametro url o file: nell'IDE di Looker, apri il file manifest.lkml del progetto e controlla la dichiarazione application:
    • Una dichiarazione application deve includere un parametro url o un parametro file, ma non entrambi.
    • Durante lo sviluppo locale: verifica che il parametro url corrisponda esattamente al protocollo (http o https), al nome host, alla porta e al percorso pubblicati dal tuo server di sviluppo locale (ad esempio, https://localhost:8080/bundle.js).
    • In produzione: verifica di aver aggiornato la dichiarazione application dal percorso di sviluppo locale url al percorso di produzione file nel tuo progetto LookML (ad esempio file: "apps/bundle.js") o nell'URL del bundle di produzione.
  • Verifica i diritti manifest.lkml: esamina il blocco entitlements nella dichiarazione application. Un'estensione non può utilizzare una risorsa Looker o un dominio esterno, a meno che l'autorizzazione non venga dichiarata esplicitamente, come segue:
    • core_api_methods: deve elencare ogni metodo dell'API Looker chiamato dall'estensione (ad esempio, core_api_methods: ["me", "all_looks", "run_inline_query"]).
    • external_api_urls: deve elencare tutti i domini esterni non Looker richiesti dall'estensione direttamente o tramite il proxy.
    • Diritti aggiuntivi: verifica se l'estensione richiede local_storage, navigation, new_window, new_window_external_urls, use_form_submit, use_embeds, use_downloads, use_iframes, use_clipboard, oauth2_urls, global_user_attributes o scoped_user_attributes.
  • Convalida, commit ed esegui il deployment: dopo aver modificato manifest.lkml, fai clic su Convalida LookML, esegui il commit delle modifiche e fai clic su Esegui il deployment in produzione in modo che la configurazione aggiornata diventi effettiva.

Risolvi i problemi relativi all'ambiente e al server di sviluppo locale

Quando sviluppi un'estensione localmente utilizzando il parametro url in manifest.lkml, il server di sviluppo locale deve essere in esecuzione e accessibile dal browser:

  • Verifica che il server di sviluppo sia in esecuzione: controlla la finestra del terminale in cui hai avviato il server di sviluppo (ad esempio, utilizzando yarn develop o npm start):
    • Verifica che la build sia stata compilata senza errori e che venga visualizzato un messaggio di ascolto (ad esempio webpack compiled successfully o listening on localhost:8080).
    • Se il server non è in esecuzione, avvialo con yarn develop o npm start.
    • Se il server è stato chiuso con un errore di sintassi o di dipendenza mancante, risolvi l'errore di codice o esegui yarn install (o npm install) per installare i pacchetti mancanti.
    • Se il server non riesce a causa di un conflitto di porte (EADDRINUSE), interrompi l'altro processo che utilizza la porta o configura il server di sviluppo e il parametro manifest.lkml url in modo che utilizzino una porta diversa.
  • Apri l'URL dell'estensione direttamente nel browser: copia il valore url da manifest.lkml (ad esempio, https://localhost:8080/bundle.js) e aprilo in una nuova scheda del browser:
    • Certificato SSL autofirmato non attendibile: i server di sviluppo locale utilizzano spesso certificati SSL autofirmati. Se il browser visualizza un avviso di sicurezza del certificato, seleziona Avanzate e vai a localhost per considerare attendibile il certificato per la sessione del browser. Finché il certificato non è attendibile, il browser blocca il caricamento del bundle all'interno di Looker iframe.
    • Connessione rifiutata o bloccata: se il browser non riesce a raggiungere l'URL, verifica che nessun firewall locale o software di sicurezza degli endpoint blocchi le connessioni a localhost sulla porta configurata.

Risolvi i problemi relativi a networking, CORS e policy di sicurezza

I browser web applicano la policy della stessa origine, che impedisce a Looker di caricare le risorse delle estensioni o di chiamare server esterni su un'origine diversa, a meno che non siano configurate le intestazioni e le policy di sicurezza della condivisione delle risorse multiorigine (CORS):

  • Identifica gli errori CORS nella console del browser: cerca i messaggi di errore nella scheda Console contenenti Cross-Origin Resource Sharing, CORS, has been blocked by CORS policy o intestazioni Access-Control-Allow-Origin mancanti.
  • Configura le intestazioni CORS del server di sviluppo locale: se utilizzi webpack-dev-server (o un bundler simile), assicurati che la configurazione devServer in webpack.config.js includa l'intestazione Access-Control-Allow-Origin: javascript devServer: { headers: { "Access-Control-Allow-Origin": "*" } }
  • Configura l'hosting di produzione e le intestazioni CORS dell'API esterna: se l'estensione carica asset o richiede dati da un servizio esterno (come Cloud Storage, Amazon S3 o un server di backend personalizzato), configura il servizio di hosting in modo che restituisca l'intestazione Access-Control-Allow-Origin che consente il dominio dell'istanza di Looker. Verifica inoltre che nessun proxy di rete o firewall rimuova le intestazioni CORS dalla risposta e assicurati che il dominio esterno sia elencato in external_api_urls in manifest.lkml.
  • Controlla il Content Security Policy (CSP) e il caricamento delle estensioni avanzate: se riscontri violazioni del CSP durante il caricamento di un'estensione, controlla l'impostazione Caricamento delle estensioni avanzate in Amministrazione > Piattaforma > Framework delle estensioni.

Risolvi i problemi di autenticazione e accesso alle API

Le estensioni interagiscono con l'API Looker per conto dell'utente che ha eseguito l'accesso tramite l'SDK Extension. Se le chiamate API non vanno a buon fine con i codici di stato 401 Unauthorized o 403 Forbidden nella scheda Rete, verifica quanto segue:

  • Fai distinzione tra gli errori 401 e 403:
    • 401 Unauthorized: la richiesta non è stata autenticata. Questo errore si verifica in genere se l'SDK dell'estensione non è stato inizializzato correttamente o se l'estensione ha tentato una chiamata API prima che l'SDK completasse l'handshake di autenticazione.
    • 403 Forbidden: la richiesta è stata autenticata, ma l'utente che ha eseguito l'accesso non dispone delle autorizzazioni Looker richieste o il manifest.lkml dell'estensione non include il metodo chiamato in core_api_methods.
  • Verifica i ruoli e le autorizzazioni degli utenti: in Amministratore > Utenti e Amministratore > Ruoli, controlla i ruoli, i set di autorizzazioni e i set di modelli assegnati all'utente che ha eseguito l'accesso:
    • Verifica che l'utente disponga delle autorizzazioni per utilizzare l'estensione, tra cui access_data (e explore o develop, se necessario) per un set di modelli che contiene il modello LookML dell'estensione e tutti i modelli su cui l'estensione esegue query.
    • Verifica che il ruolo dell'utente includa le autorizzazioni specifiche richieste da ogni endpoint API di Looker chiamato dall'estensione.
  • Assicurati che il contesto dell'SDK sia pronto prima di chiamare l'API: verifica che il codice dell'estensione attenda l'inizializzazione del contesto dell'SDK Extension prima di richiamare i metodi dell'API.

Risolvi i problemi relativi all'SDK Extension e alle dipendenze

I problemi relativi all'installazione dei pacchetti npm o Yarn o i componenti mancanti del provider di SDK possono impedire la compilazione o la connessione di un'estensione a Looker:

  • Verifica l'installazione del modulo Node.js: nel terminale, vai alla directory root del progetto di estensione e controlla la directory node_modules:
    1. Se node_modules non è presente o le dipendenze sembrano danneggiate, elimina la directory node_modules e il file di blocco (yarn.lock o package-lock.json).
    2. (Facoltativo) Se l'installazione del pacchetto non va a buon fine ripetutamente, svuota la cache del gestore di pacchetti (ad esempio, esegui npm cache clean --force).
    3. Verifica che la versione di Node.js installata sia compatibile con i requisiti del progetto, quindi esegui yarn install o npm install per eseguire un'installazione pulita.
  • Controlla l'inizializzazione di ExtensionProvider: apri il file di entry point principale dell'estensione (ad esempio App.js o index.js) e verifica che <ExtensionProvider> (importato da @looker/extension-sdk-react) includa i componenti dell'applicazione che richiedono il contesto dell'SDK Looker: javascript ReactDOM.render( <ExtensionProvider> <App /> </ExtensionProvider>, document.getElementById('root') ); Se <ExtensionProvider> non è presente o se lo hai posizionato dopo i componenti che chiamano l'SDK, i componenti secondari non possono accedere al contesto dell'SDK.

Risolvi gli errori logici e di runtime di JavaScript

Se la configurazione, il server di sviluppo, le autorizzazioni e la configurazione dell'SDK dell'estensione sono validi, il problema potrebbe essere un errore di runtime nel codice JavaScript o TypeScript personalizzato dell'estensione:

  • Analizza le analisi dello stack della console: nella scheda Console del browser, individua il messaggio di errore rosso e fai clic sulla freccia di espansione per visualizzare l'analisi dello stack completa. Le prime righe dell'analisi dello stack identificano il file e il numero di riga nel codice sorgente in cui si è verificato l'errore. Fai clic sul link del file (ad esempio, MyComponent.js:42) per passare direttamente alla riga corrispondente nella scheda Origini.
  • Verifica la presenza di valori non definiti o nulli: per errori come TypeError: Cannot read properties of undefined, verifica che il caricamento delle risposte dell'API asincrona o delle proprietà sia stato completato prima che il codice legga le proprietà nidificate. Aggiungi controlli difensivi (come if (myObject && myObject.property) o il concatenamento facoltativo myObject?.property).
  • Verifica i formati delle risposte dell'API Looker: verifica che il codice gestisca la struttura dei dati effettiva restituita dalle chiamate API Looker (ad esempio, verifica se un payload di risposta è un oggetto o un array prima di chiamare i metodi dell'array).
  • Esegui il debug con i punti di interruzione e il logging: nella scheda Origini del browser, imposta i punti di interruzione prima della riga con errori per mettere in pausa l'esecuzione e ispezionare i valori delle variabili in tempo reale oppure aggiungi istruzioni console.log() per tracciare il flusso di esecuzione.

Verifica la compatibilità della versione di Looker

Gli aggiornamenti o le modifiche principali delle funzionalità di Looker possono richiedere una versione compatibile dell'SDK Looker Extension:

  1. Controlla la versione di @looker/extension-sdk (e @looker/extension-sdk-react, se utilizzato) nel file package.json del progetto di estensione.
  2. Nell'interfaccia web di Looker, controlla la versione di release corrente dell'istanza in Guida > Informazioni o Amministrazione > Generale > Impostazioni.
  3. Confronta la versione di release di Looker con le note sulla compatibilità nella documentazione di @looker/extension-sdk.
  4. Se è stato eseguito l'upgrade della tua istanza di Looker di recente e l'estensione utilizza un SDK obsoleto o se l'estensione utilizza una funzionalità dell'SDK più recente non supportata da una versione precedente di Looker, aggiorna il pacchetto dell'SDK a una versione compatibile: bash npm install @looker/extension-sdk@latest Dopo aver aggiornato il pacchetto, reinstalla le dipendenze e riavvia il server di sviluppo.

Raccogli informazioni di diagnostica

Se non riesci a risolvere il problema dopo aver seguito i passaggi per la risoluzione dei problemi, raccogli le seguenti informazioni prima di contattare l'assistenza:

  1. Informazioni sull'istanza e sul progetto Looker:
    • URL dell'istanza di Looker (ad esempio, instance_name.looker.com).
    • Versione di release di Looker.
    • Nome del progetto LookML che contiene l'estensione e il nome application in manifest.lkml.
  2. Dettagli sulla configurazione dell'estensione e sull'SDK:
    • Una copia o uno screenshot della dichiarazione application nel file manifest.lkml.
    • La versione di @looker/extension-sdk specificata in package.json.
    • Se l'estensione è in esecuzione da un server di sviluppo locale (url) o se è stato eseguito il deployment in produzione (file).
  3. Log degli errori e screenshot:
    • Screenshot o testo completo degli errori dalle schede Console e Rete del browser (incluse le intestazioni delle richieste e i payload delle risposte per le richieste 4xx o 5xx non andate a buon fine).
    • Se le chiamate API restituiscono costantemente errori del server 5xx, estratti di log corrispondenti da looker.log (per le istanze ospitate dal cliente) o da Esplora log in Logging (per le istanze di Looker (Google Cloud core)).
  4. Riepilogo della risoluzione dei problemi e passaggi per la riproduzione:
    • Un riepilogo dei passaggi per la risoluzione dei problemi che hai già eseguito e dei relativi risultati.
    • I passaggi esatti per riprodurre il problema o un esempio minimo riproducibile se sospetti un problema nel framework di estensione Looker o nell'SDK di estensione.

Contatta l'assistenza

Se hai verificato tutti i passaggi precedenti e il problema non è stato ancora risolto: