Gestionar errores y mensajes de error en conectores comunitarios

Si quieres ofrecer una buena experiencia de usuario, tu código debe gestionar errores correctamente. Muestra a los usuarios mensajes de error que les indiquen qué pasos deben seguir para solucionar problemas.

Este documento indica qué errores pueden producirse con los conectores, cómo funcionan los mensajes de error y cómo gestionar adecuadamente esos errores.

Para saber cómo gestionar excepciones en JavaScript, consulta la declaración try...catch.

Tipos de errores

Por lo general, los tipos y las causas de los errores que los usuarios se pueden encontrar al utilizar un conector se clasifican en una de estas tres categorías:

  1. Errores internos de conectores
  2. Errores externos de conectores
  3. Errores de Data Studio

Los desarrolladores deben gestionar los errores internos y externos de sus conectores. Estos errores se deben al código que los desarrolladores hayan creado.

Errores internos de conectores

Los errores internos se producen cuando los conectores están en ejecución. Un ejemplo de este tipo de error sería un conector no puede analizar una respuesta de una API mientras getData() está en ejecución. Estos errores deben preverse y gestionarse con explicaciones fáciles de comprender siempre que sea necesario.

Consulta más información sobre cómo gestionar los errores internos de los conectores en el apartado Prácticas recomendadas para gestionar errores de conectores.

Errores externos de conectores

Los errores externos de conectores se producen después de que los conectores se ejecuten. Por ejemplo, cuando una solicitud getData() para obtener datos de tres campos solo devuelve datos de dos. En este ejemplo, aunque el conector se ha ejecutado, no cumplió con la solicitud de Data Studio. Estos errores se pueden evitar haciendo pruebas exhaustivas.

En general, los errores externos de los conectores se pueden corregir consultando los detalles del error en cuestión (si están disponibles) y depurando el código para identificar el problema. Consulta más información sobre cómo depurar código.

Errores de Data Studio

Los errores de Data Studio no están relacionados con el código del conector. Por ejemplo, supongamos que un usuario intenta usar un gráfico de serie temporal con una fuente de datos que no tiene ninguna dimensión de fecha ni de hora.

Si el error no está directamente relacionado con el conector, el desarrollador del conector no puede hacer nada para solucionarlo. Los usuarios pueden encontrar ayuda adicional en el Centro de Ayuda de Data Studio.

Mostrar mensajes de error

Mostrar detalles de error dependiendo de si un usuario es administrador o no

Cuando se produce un error con un conector, los detalles que Data Studio muestra dependen de si el usuario es administrador o no.

  • Si el usuario es administrador, verá todos los detalles, como el mensaje de error, el tipo de error y el rastreo de la pila.
  • Si el usuario no es administrador, solo verá los detalles si el error incluye un mensaje fácil de comprender. Consulta más información al respecto en el apartado Mostrar errores a los usuarios.

Mostrar errores a los usuarios

De forma predeterminada, solo los administradores de los conectores ven los detalles de los errores. Así no se revela información sensible de forma involuntaria, como una clave de API en el rastreo de una pila. Para mostrar mensajes de error a usuarios que no son administradores, usa el objeto newUserError() del servicio Apps Script de Data 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() determina el texto que se mostrará a todos los usuarios y setDebugText() indica el texto que solo se mostrará a los administradores.

Prácticas recomendadas para gestionar errores de conectores

Deberías identificar y gestionar todos los errores posibles durante la ejecución del código de tu conector. Estas son algunas de las operaciones habituales que pueden ocasionar errores o llevar a estados no deseados:

  • No se ha podido obtener una determinada URL (errores temporales, tiempos de espera agotados).
  • No hay datos disponibles del periodo de tiempo solicitado.
  • Los datos de la API no se pueden analizar ni formatear.
  • Los tokens de autorización se han revocado.

Gestionar errores que se pueden corregir

Si en algunas partes de la ejecución del conector pueden producirse errores que es posible corregir, deberías solucionarlos. Por ejemplo, si una solicitud que se ha hecho a una API falla por un motivo que no es grave (como una sobrecarga del servidor), se debería intentar hacer de nuevo antes de mostrar un mensaje de error.

Identificar errores y mostrar mensajes de error

Los errores que no se pueden corregir deben capturarse y mostrarse de nuevo. Volver a mostrar un error determinado debería ayudar a los usuarios a comprender por qué ese error se ha producido. Si el problema se puede solucionar, se deben proporcionar detalles sobre las medidas que hay que tomar.

Consulta Mostrar errores a los usuarios.

Registrar errores en Stackdriver

Usa Stackdriver para registrar mensajes de error y de otros tipos, ya que permite saber de dónde provienen los errores, depurar problemas y descubrir excepciones no gestionadas.

Para obtener más información sobre cómo usar Stackdriver Error Reporting, cómo habilitar el registro de excepciones de secuencias de comandos y cuáles son las distintas formas de identificar a los usuarios de manera segura para depurar el código, consulta cómo utilizar Stackdriver Logging.

OBSOLETO: Usar el prefijo DS_USER: en los mensajes que se pueden mostrar a los usuarios que no son administradores

Si quieres mostrar mensajes de error fáciles de entender a los usuarios que no sean administradores, incluye el prefijo DS_USER:. Este prefijo solo sirve para identificar los mensajes de error que se pueden mostrar a los usuarios que no son administradores. No aparece en el texto de los mensajes.

A continuación, se incluyen dos ejemplos de código; uno mostrará el mensaje de error a los usuarios que no son administradores, y el otro, solo a los usuarios que son administradores:

data-studio/errors.gs
// 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');
    }