Para proporcionar una buena experiencia del usuario, tu código debe controlar los errores correctamente. Presenta a los usuarios mensajes de error prácticos que describan los pasos correctivos para resolver el problema.
En este documento, se describen los errores que pueden ocurrir con los conectores, cómo funcionan los mensajes de error y cómo controlar correctamente los errores de los conectores.
Nota: Para obtener más información sobre el manejo de excepciones en JavaScript, consulta la instrucción try…catch.
Tipos de errores
Los tipos y las causas de los errores que un usuario puede encontrar cuando usa tu conector suelen clasificarse en una de las siguientes tres categorías:
El desarrollador del conector debe controlar los errores internos y externos del conector. Estos errores se producen debido al código creado por el desarrollador.
Error interno del conector
Los errores internos del conector se producen durante la ejecución del conector. Por ejemplo, si un conector no puede analizar una respuesta de la API durante la ejecución de getData().
Estos errores se deben anticipar y controlar con explicaciones fáciles de entender para el usuario cuando corresponda.
Para obtener más información sobre cómo controlar los errores internos del conector, consulta Prácticas recomendadas para controlar los errores del conector.
Error externo del conector
Los errores externos del conector se producen después de la ejecución del conector. Por ejemplo, cuando una solicitud de getData() para tres campos solo devuelve datos para dos. Aunque el conector completó la ejecución, no satisfizo la solicitud de Looker Studio. Las pruebas exhaustivas pueden evitar estos errores.
Por lo general, los errores externos del conector se pueden corregir revisando los detalles del error (si están disponibles) y depurando el código para identificar el problema. Para obtener más información sobre cómo depurar tu conector, consulta Depura tu código.
Error de Looker Studio
Los errores de Looker Studio no están relacionados con el código de tu conector. Por ejemplo, si un usuario intenta usar un gráfico de series temporales con una fuente de datos que no tiene una dimensión de fecha y hora.
Si el error no está directamente relacionado con el conector, el desarrollador del conector no debe realizar ninguna acción. Los usuarios pueden obtener ayuda adicional en el Centro de ayuda de Looker Studio.
Cómo mostrar mensajes de error
Cómo se muestran los detalles del error según el estado de administrador
Cuando un conector arroja un error, Looker Studio muestra el mensaje de error según el estado de administrador del usuario.
- Si el usuario es un usuario administrador, verá todos los detalles. Esto incluye el mensaje de error, el tipo de error y el seguimiento de pila.
- Si el usuario no es administrador, solo verá los detalles si el error incluye un mensaje fácil de entender. Para obtener más información sobre cómo mostrar mensajes de error a los usuarios que no son administradores, consulta Cómo generar errores visibles para el usuario.
Cómo arrojar errores visibles para el usuario
De forma predeterminada, solo los administradores de conectores ven los detalles de los errores. Esto ayuda a evitar la divulgación accidental de información sensible, como una clave de API en un registro de pila. Para mostrar mensajes de error a los usuarios que no son administradores, usa newUserError() del servicio de Apps Script de Looker Studio.
Ejemplo:
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();
}
En este ejemplo, setText() establece el texto que se mostrará a todos los usuarios, mientras que setDebugText() establece el texto que solo se mostrará a los usuarios administradores.
Prácticas recomendadas para controlar los errores del conector
Debes intentar detectar y controlar la mayor cantidad posible de errores durante la ejecución del código del conector. Por ejemplo, algunas operaciones comunes que pueden causar errores o un estado no deseado son las siguientes:
- Intento fallido de recuperación de URL (errores transitorios, tiempos de espera)
- No hay datos disponibles para el período solicitado
- No se pueden analizar ni dar formato a los datos de la API
- Se revocaron los tokens de autorización
Cómo controlar errores recuperables
Se deben controlar los puntos de ejecución del conector que pueden fallar, pero que se pueden recuperar. Por ejemplo, si falla una solicitud a la API por un motivo no fatal (p.ej., reducción de carga del servidor), se debe reintentar antes de arrojar un error.
Cómo detectar y generar errores
Los errores irrecuperables se deben detectar y volver a arrojar. El error que se vuelve a arrojar debería ayudar a los usuarios a comprender por qué se produjo el error. Si el problema se puede solucionar, se deben proporcionar detalles sobre la acción correctiva.
Consulta cómo mostrar errores a los usuarios.
Registra errores en Stackdriver
Usa Stackdriver para registrar errores y otros mensajes. Esto ayuda a comprender los errores, depurar los problemas y descubrir las excepciones no controladas.
Para obtener más información sobre Stackdriver Error Reporting, cómo habilitar el registro de excepciones para una secuencia de comandos y cómo identificar de forma segura a los usuarios con fines de depuración, consulta Uso de Stackdriver Logging.
OBSOLETO: Usa el prefijo DS_USER: para los mensajes de error seguros
Para proporcionar mensajes de error fáciles de usar a los usuarios que no son administradores, incluye el prefijo DS_USER: con los mensajes de error. Este prefijo se usa para identificar mensajes seguros para usuarios que no son administradores y no se incluye en el mensaje de error real.
En los siguientes ejemplos, se incluye un caso en el que se mostrará un mensaje de error a los usuarios que no son administradores y otro en el que el mensaje de error solo se mostrará a los usuarios administradores: