Per offrire una buona esperienza utente, il codice deve gestire correttamente gli errori. Mostra agli utenti messaggi di errore pratici che descrivono i passaggi correttivi per risolvere il problema.
Questo documento descrive gli errori che possono verificarsi con i connettori, come funzionano i messaggi di errore e come gestirli correttamente.
Informazioni: per scoprire di più sulla gestione delle eccezioni in JavaScript, consulta try...catch statement.
Tipi di errori
I tipi e le cause degli errori che un utente può riscontrare quando utilizza il tuo connettore in genere rientrano in una delle seguenti tre categorie:
Gli errori interni ed esterni del connettore devono essere gestiti dallo sviluppatore del connettore. Questi errori si verificano a causa del codice creato dallo sviluppatore.
Errore interno del connettore
Gli errori interni del connettore si verificano durante l'esecuzione del connettore. Ad esempio, se un
connettore non riesce ad analizzare una risposta API durante l'esecuzione di getData().
Questi errori devono essere previsti e gestiti con spiegazioni intuitive per l'utente, se applicabile.
Per saperne di più sulla gestione degli errori interni del connettore, consulta Best practice per la gestione degli errori del connettore.
Errore esterno del connettore
Gli errori esterni del connettore si verificano dopo l'esecuzione del connettore. Ad esempio, quando una
richiesta getData() per tre campi restituisce dati solo per due. Sebbene il
connettore abbia completato l'esecuzione, non ha soddisfatto la richiesta di Looker
Studio. Test approfonditi possono prevenire questi errori.
Gli errori esterni del connettore in genere possono essere corretti esaminando i dettagli dell'errore (se disponibili) ed eseguendo il debug del codice per identificare il problema. Per ulteriori informazioni sul debug del connettore, vedi Eseguire il debug del codice.
Errore di Looker Studio
Gli errori di Looker Studio non sono correlati al codice del connettore. Ad esempio, se un utente tenta di utilizzare un grafico delle serie temporali con un'origine dati senza dimensione data/ora.
Se l'errore non è direttamente correlato al connettore, lo sviluppatore del connettore non deve intraprendere alcuna azione. Gli utenti possono trovare ulteriore assistenza visitando il Centro assistenza Looker Studio.
Visualizzazione dei messaggi di errore
Visualizzazione dei dettagli dell'errore in base allo stato di amministratore
Quando un connettore genera un errore, Looker Studio mostra il messaggio di errore a seconda dello stato di amministratore dell'utente.
- Se l'utente è un utente amministratore, visualizzerà tutti i dettagli. Sono inclusi il messaggio di errore, il tipo di errore e l'analisi dello stack.
- Se l'utente non è un utente amministratore, vedrà i dettagli solo se l'errore include un messaggio intuitivo. Per scoprire di più sulla visualizzazione dei messaggi di errore per gli utenti non amministratori, consulta Generazione di errori visibili agli utenti.
Generazione di errori visibili all'utente
Per impostazione predefinita, solo gli amministratori del connettore visualizzano i dettagli dell'errore. In questo modo si evita la divulgazione involontaria di informazioni sensibili, ad esempio una chiave API in una traccia dello stack. Per mostrare i messaggi di errore agli utenti non amministratori, utilizza newUserError() dal servizio Apps Script di Looker Studio.
Esempio:
try {
// API request that can be malformed.
getDataFromAPI();
} catch (e) {
DataStudioApp.createCommunityConnector()
.newUserError()
.setDebugText('Error fetching data from API. Exception details: ' + e)
.setText('There was an error communicating with the service. Try again later, or file an issue if this error persists.')
.throwException();
}
In questo esempio, setText() imposta il testo che verrà mostrato a tutti gli utenti,
mentre setDebugText() imposta il testo che verrà mostrato solo agli utenti amministratori.
Best practice per la gestione degli errori del connettore
Devi tentare di rilevare e gestire il maggior numero possibile di errori durante l'esecuzione del codice del connettore. Ad esempio, alcune operazioni comuni che potrebbero causare errori o uno stato indesiderato includono:
- Tentativo di recupero dell'URL non riuscito (errori temporanei, timeout)
- Nessun dato disponibile per il periodo di tempo richiesto
- I dati dell'API non possono essere analizzati o formattati
- I token di autorizzazione sono stati revocati
Gestire gli errori recuperabili
I punti di esecuzione del connettore che possono non riuscire, ma sono recuperabili, devono essere gestiti. Ad esempio, se una richiesta API non va a buon fine per un motivo non irreversibile (ad es. riduzione del carico del server), deve essere riprovata prima di generare un errore.
Rilevare e generare errori
Gli errori non recuperabili devono essere rilevati e generati nuovamente. L'errore rilanciato dovrebbe aiutare gli utenti a capire perché si è verificato. Se il problema può essere risolto, devono essere forniti i dettagli dell'azione correttiva.
Consulta la sezione Generare errori visibili agli utenti.
Registra gli errori in Stackdriver
Utilizza Stackdriver per registrare gli errori e altri messaggi. Ciò consente di comprendere gli errori, eseguire il debug dei problemi e scoprire le eccezioni non gestite.
Per scoprire di più su Stackdriver Error Reporting, su come attivare la registrazione delle eccezioni per uno script e su come identificare in modo sicuro gli utenti a scopo di debug, consulta Utilizzo di Stackdriver Logging.
DEPRECATO: utilizza il prefisso DS_USER: per i messaggi di errore sicuri
Per fornire messaggi di errore di facile comprensione agli utenti non amministratori, includi il prefisso
DS_USER: nei messaggi di errore. Questo prefisso viene utilizzato per identificare i messaggi sicuri per gli utenti non amministratori e non è incluso nel messaggio di errore effettivo.
I seguenti esempi includono un caso in cui verrà mostrato un messaggio di errore agli utenti non amministratori e un altro in cui verrà mostrato un messaggio di errore solo agli utenti amministratori: