Обработка ошибок и показ сообщений в коннекторах с открытым кодом

Чтобы коннектором было удобно пользоваться, он должен корректно обрабатывать возможные ошибки. Позаботьтесь о том, чтобы пользователи получали оповещения с понятными инструкциями по устранению ошибок.

В этом документе рассказывается об ошибках, которые могут произойти при использовании коннектора, а также о показе сообщений об ошибках и о том, как правильно эти ошибки обрабатывать.

Подробную информацию об обработке исключений можно найти в статье про операторы try…catch.

Типы ошибок

Типы и причины ошибок, с которыми пользователь может столкнуться при использовании вашего коннектора, можно разделить на три категории:

  1. Внутренние ошибки коннектора
  2. Внешние ошибки коннектора
  3. Ошибки Студии данных

За обработку внутренних и внешних ошибок отвечает разработчик коннектора, поскольку эти ошибки происходят в ходе выполнения кода коннектора.

Внутренние ошибки коннектора

Внутренние ошибки коннектора происходят во время его выполнения – например, когда коннектору не удается проанализировать ответ API при выполнении функции getData(). Для подобных случаев необходимо предусмотреть понятные для пользователей сообщения.

Подробная информация об обработке внутренних ошибок коннектора представлена в этом разделе.

Внешние ошибки коннектора

Внешними называются ошибки, которые случаются после выполнения коннектора – например, когда функция getData() запрашивает у коннектора три поля, а он возвращает только два (действие коннектора успешно выполнено, но запрос из Студии данных не удовлетворен). Подобные исключения можно предотвратить путем тщательного тестирования.

Внешнюю ошибку обычно можно исправить, изучив сведения о ней (если доступны) и выполнив отладку кода. Подробнее…

Ошибки Студии данных

Ошибки Студии данных не связаны с выполнением кода коннектора. Например, к ним относится ошибка, возникающая при попытке использовать диаграмму временного ряда с источником данных, в котором не заданы дата и время.

Если ошибка напрямую не связана с кодом коннектора, то от разработчика не требуется никаких действий. Подробнее…

Показ сообщений об ошибках

Разные сообщения для администраторов и пользователей

При возникновении ошибки в коннекторе Студия данных показывает разные сообщения в зависимости от статуса пользователя.

  • Администраторы видят все сведения, включая сообщение об ошибке и ее типе, а также трассировку стека.
  • Остальные пользователи видят подробную информацию только в том случае, если в сообщении будет предусмотрено понятное широкому кругу пользователей описание ошибки. Подробнее…

Сообщения об ошибках для рядовых пользователей

По умолчанию подробные сведения об ошибках видны только администраторам коннектора. Это нужно, чтобы не допустить случайного раскрытия конфиденциальной информации, например ключа API, в трассировке стека. Чтобы показывать сообщения об ошибках рядовым пользователям, используйте метод newUserError(), который доступен на платформе Apps Script.

Пример:

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();

    }
    

В этом примере переменная setText() задает текст сообщения, который смогут увидеть все пользователи, а переменная setDebugText() – текст для администраторов.

Рекомендации по обработке ошибок коннектора

Рекомендуется отслеживать и обрабатывать как можно больше ошибок во время выполнения кода коннектора. Ниже перечислены наиболее типичные события, которые могут привести к ошибкам или нежелательному состоянию коннектора:

  • не удалось получить URL-адрес (временные ошибки, тайм-ауты);
  • нет данных для указанного периода;
  • данные из API не могут быть проанализированы или отформатированы;
  • токены авторизации отозваны.

Обработка устранимых ошибок

Если во время работы коннектора могут возникать сбои, которые можно устранить, предусмотрите порядок действий для таких случаев. Например, если при выполнении запроса к API происходит некритическая ошибка (к примеру, падение мощности сервера), следует повторить попытку, прежде чем показывать сообщение об ошибке.

Отслеживание ошибок и показ сообщений о них

Неустранимые ошибки необходимо отслеживать и сообщать о них пользователю, чтобы тот мог определить причину проблемы. Если проблему можно исправить, то в сообщение нужно включить инструкции о том, как это сделать.

Подробнее о сообщениях об ошибках для пользователей

Запись ошибок в журнал Stackdriver

Пакет Stackdriver позволяет вести журнал ошибок и других сообщений. Так вам будет удобнее анализировать причины ошибок и выявлять необработанные исключения.

Узнать больше о Stackdriver Error Reporting, а также о том, как включить регистрацию исключений для скрипта и безопасно идентифицировать пользователей с целью отладки, можно в разделе Использование Stackdriver Logging.

УСТАРЕЛО! Использование префикса DS_USER: для безопасных сообщений об ошибках

Чтобы показывать сообщения об ошибках пользователям без прав администратора, добавьте к коду ошибок префикс DS_USER:. Этот префикс используется, чтобы обозначить сообщения, которые безопасно показывать пользователям, не имеющим прав администратора. Он не отображается в сообщении об ошибке.

В первом примере ниже сообщение об ошибке показывается пользователям без прав администратора, а во втором – только администраторам.

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');
    }