Gestione degli errori e messaggi per i connettori della community

Per offrire una buona esperienza utente, il tuo codice deve gestire correttamente gli errori. Presenta agli utenti messaggi di errore strategici che descrivono i passaggi correttivi per la risoluzione del problema.

Questo documento descrive gli errori che possono verificarsi con i connettori, come funzionano i messaggi di errore e come gestire correttamente gli errori del connettore.

Informazioni: per ulteriori informazioni sulla gestione delle eccezioni in JavaScript, consulta l'istruzionetry...catch.

Tipi di errori

I tipi e le cause di errori che un utente può riscontrare quando utilizza il connettore in genere rientrano in una delle tre categorie seguenti:

1. errori interni del connettore
2. errori esterni del connettore
3. Errori di Looker Studio

Gli errori interni ed esterni del connettore devono essere gestiti dallo sviluppatore del connettore. Questi errori si verificano a causa di un 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 può analizzare una risposta dell'API durante l'esecuzione di getData(). Ove applicabili, questi errori devono essere previsti e gestiti con spiegazioni semplici da usare.

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

Dopo l'esecuzione, si verificano errori esterni del connettore. Ad esempio, quando una richiesta getData() per tre campi restituisce solo i dati per due. Sebbene il connettore abbia completato l'esecuzione, non ha soddisfatto la richiesta di Looker Studio. Test accurati possono prevenire questi errori.

In genere, gli errori esterni del connettore possono essere risolti esaminando i dettagli dell'errore (se disponibili) ed eseguendo il debug del codice per identificare il problema. Per ulteriori informazioni sul debug del connettore, consulta la pagina Eseguire il debug del codice.

Errore di Looker Studio

Gli errori di Looker Studio non riguardano il 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 fare nulla. Per ulteriore assistenza, gli utenti possono visitare il Centro assistenza Looker Studio.

Visualizzazione dei messaggi di errore

Visualizzazione dei dettagli dell'errore in base allo stato dell'amministratore

Quando un connettore genera un errore, Looker Studio mostra il messaggio di errore in base allo stato di amministratore dell'utente.

• Se l'utente è un utente amministratore vedrà tutti i dettagli. Sono inclusi il messaggio, 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 facile da usare. Per scoprire di più sulla visualizzazione dei messaggi di errore per gli utenti non amministratori, vedi Generazione di errori per gli utenti.

Punto chiave: implementa isAdminUser() per identificare gli amministratori in modo che venga mostrato il giusto livello di dettaglio agli utenti del connettore.

Generazione di errori per gli utenti

Per impostazione predefinita, solo gli amministratori dei connettori visualizzano i dettagli degli errori. Ciò consente di evitare la divulgazione involontaria di informazioni sensibili, come 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 cercare di individuare e gestire il maggior numero possibile di errori durante l'esecuzione del codice del connettore. Ad esempio, alcune operazioni comuni che possono causare errori o uno stato indesiderato includono:

• Un 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 che sono recuperabili, devono essere gestiti. Ad esempio, se una richiesta API non va a buon fine per un motivo non irreversibile (ad esempio, una perdita di carico del server), deve essere effettuato un nuovo tentativo prima di generare un errore.

Errori di rilevamento e generazione

Gli errori non recuperabili devono essere rilevati e gettati di nuovo. L'errore ripetuto dovrebbe aiutare gli utenti a capire perché si è verificato. Se il problema può essere risolto, è necessario fornire i dettagli sull'azione correttiva.

Consulta la sezione Generazione di errori per gli utenti.

Registra errori in Stackdriver

Utilizza Stackdriver per il logging degli errori e di altri messaggi. Ciò consente di comprendere gli errori, eseguire il debug dei problemi e scoprire le eccezioni non gestite.

Per ulteriori informazioni su Stackdriver Error Reporting, su come abilitare il logging delle eccezioni per uno script e su come identificare gli utenti in modo sicuro a scopo di debug, consulta la pagina relativa all'utilizzo di Stackdriver Logging.

OBSOLETO: utilizza il prefisso DS_USER: per i messaggi di errore sicuri

Attenzione: questa funzionalità è stata ritirata e verrà rimossa a giugno 2019. Esegui la migrazione a newUserError(). Consulta la sezione Generazione di errori per gli utenti.

Per fornire messaggi di errore facili da usare agli utenti non amministratori, includi il prefisso DS_USER: con i messaggi di errore. Questo prefisso viene utilizzato per identificare i messaggi sicuri destinati agli utenti non amministratori e non è incluso nel messaggio di errore effettivo.

Gli esempi seguenti includono un caso in cui un messaggio di errore verrà mostrato agli utenti non amministratori, mentre un altro caso in cui un messaggio di errore verrà mostrato solo agli utenti amministratori:

data-studio/errors.gs

Visualizza su GitHub

// Admin and non-admin users will see the following error.
try {
  // Code that might fail.
} catch (e) {
  throw new Error('DS_USER:This will be shown to admin & non-admin.');
}

// Only admin users will see the following error.
try {
  // Code that might fail.
} catch (e) {
  throw new Error('This message will only be shown to admin users');
}

Nota: il prefisso DS_USER: identifica solo i messaggi sicuri destinati agli utenti non amministratori e non è incluso nel messaggio di errore effettivo mostrato agli utenti.