Manejo de errores y mensajes para los conectores de la comunidad

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.

Información: 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 pertenecer a una de las siguientes tres categorías:

1. Errores internos del conector
2. Errores externos del conector
3. [Errores de Data Studio]

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 usar cuando corresponda.

Para obtener más información sobre el manejo de errores internos del conector, consulta Prácticas recomendadas para el manejo de 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 getData() para tres campos solo muestra datos para dos. Aunque el conector completó la ejecución, no satisfizo la solicitud de Data 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 la depuración de tu conector, consulta Depura tu código.

Error de Data Studio

Los errores de Data Studio son errores que 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 sin 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 visitando el [Centro de ayuda de Data Studio].

Cómo mostrar mensajes de error

Cómo mostrar detalles de errores según el estado de administrador

Cuando un conector arroja un error, Data 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 un usuario administrador, solo verá los detalles si el error incluye un mensaje fácil de usar. Para obtener más información sobre cómo mostrar mensajes de error a usuarios que no son administradores, consulta Cómo arrojar errores que se muestran al usuario.

Punto clave: Implementa isAdminUser() para identificar a los administradores de modo que se muestre el nivel de detalle correcto a los usuarios del conector.

Cómo arrojar errores que se muestran al usuario

De forma predeterminada, solo los administradores del conector ven los detalles del error. 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 usuarios que no son administradores, usa newUserError() del servicio de 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() 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 el manejo de 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 incluyen las siguientes:

• Un 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 una solicitud a la API falla por un motivo recuperable (p.ej., la reducción de carga del servidor), se debe reintentar antes de arrojar un error.

Cómo detectar y arrojar errores

Se deben detectar y volver a arrojar los errores no recuperables. El error que se vuelve a arrojar debe ayudar a los usuarios a comprender por qué se produjo el error. Si se puede solucionar el problema, se deben proporcionar detalles sobre la medida correctiva.

Consulta cómo arrojar errores que se muestran al usuario.

Cómo registrar errores en Stackdriver

Usa Stackdriver para registrar errores y otros mensajes. Esto ayuda a comprender los errores, depurar problemas y descubrir 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 para fines de depuración, consulta Cómo usar Stackdriver Logging.

EN DESUSO: Usa el prefijo DS_USER: para mensajes de error seguros

Precaución: Esta funcionalidad está obsoleta y se quitará en junio de 2019. Migra a newUserError(). Consulta cómo arrojar errores que se muestran al usuario.

Para proporcionar mensajes de error fáciles de usar a 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 usuarios que no son administradores y otro en el que solo se mostrará un mensaje de error a usuarios administradores:

data-studio/errors.gs

Ver en GitHub

function showErrorToAllUsers() {
  try {
    // Code that might fail.
    throw new Error("Something went wrong");
  } catch (e) {
    throw new Error("DS_USER:This will be shown to admin & non-admin.");
  }
}

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

Nota: El prefijo DS_USER: solo identifica mensajes seguros para usuarios que no son administradores, no se incluye en el mensaje de error real que se muestra a los usuarios.