Para proporcionar una buena experiencia del usuario, tu código debe manejar 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 manejar adecuadamente los errores de los conectores.
Información: Para obtener más información sobre cómo manejar las excepciones en JavaScript, consulta la instrucción try...catch.
Tipos de errores
Por lo general, los tipos y las causas de errores que puede encontrar un usuario cuando usa el conector se clasifican en una de las siguientes tres categorías:
El desarrollador del conector debe controlar los errores internos y externos del conector. Estos errores ocurren debido al código creado por el desarrollador.
Error interno del conector
Se producen errores internos del conector 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 deben anticiparse y abordarse con explicaciones fáciles de comprender cuando corresponda.
Para obtener más información sobre cómo manejar los errores internos del conector, consulta Prácticas recomendadas para manejar los errores del conector.
Error externo del conector
Se producen errores externos con el conector después de la ejecución del conector. Por ejemplo, cuando una solicitud getData() de tres campos solo muestra datos de dos. Aunque el conector completó la ejecución, no cumplió con la solicitud de Looker Studio. Realizar pruebas exhaustivas puede 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. Si deseas obtener más información para depurar el conector, consulta Cómo depurar tu código.
Error de Looker Studio
Los errores de Looker Studio son errores que no están relacionados con el código del conector. Por ejemplo, si un usuario intenta usar un gráfico de series temporales con una fuente de datos sin dimensión de fecha y hora.
Si el error no está directamente relacionado con el conector, no es necesario que el desarrollador del conector tome ninguna medida. Los usuarios pueden encontrar ayuda adicional en el Centro de ayuda de Looker Studio.
Se muestran mensajes de error
Se muestran los detalles del error según el estado de administrador
Cuando un conector muestra 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 usar. Si deseas obtener más información para mostrar mensajes de error a los usuarios que no son administradores, consulta Cómo arrojar errores orientados al usuario.
Muestra errores para el usuario
De forma predeterminada, solo los administradores de conectores ven los detalles de los errores. Esto ayuda a evitar la divulgación involuntaria de información sensible, como una clave de API en un seguimiento de pila. Para mostrar mensajes de error a los usuarios que no son administradores, usa newUserError() desde el servicio 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 manejar los errores del conector
Debes intentar detectar y manejar la mayor cantidad de errores posible durante la ejecución del código del conector. Por ejemplo, algunas operaciones comunes que pueden causar errores o un estado no deseado incluyen las siguientes:
- Error en el intento de recuperación de la URL (errores transitorios, tiempos de espera agotados)
- No hay datos disponibles para el período solicitado
- Los datos de la API no se pueden analizar ni formatear
- Se revocaron los tokens de autorización
Cómo manejar errores recuperables
Se deben controlar los puntos de ejecución del conector que pueden fallar, pero se pueden recuperar. Por ejemplo, si una solicitud a la API falla por un motivo recuperable (p.ej., la disminución de la carga del servidor), se debe reintentar antes de generar un error.
Detecta y arroja errores
Los errores no recuperables se deben detectar y volver a arrojar. Este error debería ayudar a los usuarios a comprender por qué ocurrió. Si el problema se puede solucionar, debes proporcionar detalles sobre las medidas correctivas.
Consulta cómo arrojar errores orientados al usuario.
Registra errores en Stackdriver
Usar Stackdriver para registrar errores y otros mensajes Esto ayuda a comprender los errores, los problemas de depuración y el descubrimiento de 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 Usa Stackdriver Logging.
OBSOLETO: Usa el prefijo DS_USER: para 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 mensajes de error. Este prefijo se usa a fin de 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 solo se mostrará un mensaje de error a los usuarios administradores: