Gestione degli errori e messaggi per i connettori della community

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

Questo documento descrive gli errori che possono verificarsi con i connettori, in che modo e come gestire correttamente gli errori del connettore.

Informazioni: per saperne di più sulla gestione delle eccezioni in JavaScript, consulta prova...l'istruzionecatch.

Tipi di errori

I tipi e le cause degli errori che un utente può riscontrare durante l'utilizzo del tuo di solito 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 dal connettore. sviluppatore. Questi errori si verificano a causa di codice creato dallo sviluppatore.

Errore interno del connettore

Gli errori interni del connettore si verificano durante l'esecuzione del connettore. Ad esempio, se un Il connettore non può analizzare una risposta dell'API durante l'esecuzione di getData(). Questi errori devono essere previsti e gestiti con spiegazioni facili da usare ove applicabile.

Per ulteriori informazioni 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 solo i dati per due. Sebbene ha completato l'esecuzione del connettore, non ha soddisfatto la richiesta di Looker Studio. Eseguire test accurati può evitare questi errori.

In genere, gli errori esterni del connettore possono essere corretti esaminando i dettagli dell'errore (se disponibile) e il debug del codice per identificare il problema. Per ulteriori informazioni per il debug del connettore, consulta Eseguire il debug del codice.

Errore di Looker Studio

Gli errori di Looker Studio sono errori non correlati al codice del connettore. Ad esempio: se un utente tenta di utilizzare un grafico delle serie temporali con un'origine dati senza data/ora.

Se l'errore non è direttamente correlato al connettore, non è richiesta alcuna azione. che lo sviluppatore del connettore possa eseguire. Gli utenti possono trovare ulteriore assistenza visitando la pagina nel 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 questo messaggio. a seconda dello stato di amministratore dell'utente.

• Se l'utente è un utente amministratore, vedrà 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 include un messaggio facile da usare. Per scoprire di più sulla visualizzazione degli errori ai messaggi indirizzati a utenti non amministratori, vedi Generare errori rivolti agli utenti.

di Gemini Advanced.

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

Generare errori rivolti agli utenti

Per impostazione predefinita, solo gli amministratori del connettore visualizzano i dettagli degli errori. Ciò aiuta a prevenire divulgazione involontaria di informazioni sensibili, ad esempio una chiave API in uno stack traccia. Per mostrare i messaggi di errore agli utenti che non sono amministratori, utilizza newUserError() dalla 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 amministratori.

Best practice per la gestione degli errori del connettore

Devi cercare di individuare e gestire il maggior numero possibile di errori durante dell'esecuzione del codice del connettore. Ad esempio, alcune operazioni comuni che che causano 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 dovrebbero essere gestiti. Ad esempio, se una richiesta API non va a buon fine per un motivo non irreversibile (ad es. perdita di carico del server), questo dovrebbe ritentare prima di generare un errore.

Individua e genera errori

Gli errori non recuperabili devono essere rilevati e recuperati. L'errore è stato riproposto deve aiutare gli utenti a capire perché si è verificato l'errore. Se il problema può essere risolto è necessario fornire dettagli sulle azioni correttive.

Consulta la sezione relativa alla generazione di errori riscontrati dagli utenti.

Registra errori in Stackdriver

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

Per saperne di più su Stackdriver Error Reporting, su come abilitare il logging delle eccezioni per uno script e come identificare in modo sicuro gli utenti a scopo di debug, consulta 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 migrazione a newUserError(). Consulta la sezione relativa alla creazione di errori riscontrati dagli utenti.

Per fornire messaggi di errore intuitivi agli utenti non amministratori, includi il Prefisso DS_USER: con messaggi di errore. Questo prefisso viene utilizzato per identificare per gli utenti che non sono amministratori e non è incluso nel messaggio di errore effettivo.

I seguenti esempi includono un caso in cui un messaggio di errore verrà mostrato a utenti non amministratori un altro luogo dove un messaggio di errore verrà mostrato solo all'amministratore utenti:

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 per gli utenti che non sono amministratori, non sia incluso nel messaggio di errore effettivo mostrato agli utenti.