Обработка ошибок и сообщения для соединителей сообщества

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

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

Информация: Чтобы узнать больше об обработке исключений в JavaScript, см. блок try...catch .

Типы ошибок

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

1. внутренние ошибки коннектора
2. внешние ошибки коннектора
3. Ошибки Looker Studio

Внутренние и внешние ошибки коннектора должны обрабатываться разработчиком коннектора. Эти ошибки возникают из-за кода, написанного разработчиком.

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

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

Для получения дополнительной информации об обработке внутренних ошибок коннектора см. раздел «Рекомендации по обработке ошибок коннектора» .

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

Внешние ошибки коннектора возникают после его выполнения. Например, когда запрос getData() для трех полей возвращает данные только для двух. Хотя коннектор завершил выполнение, он не удовлетворил запрос от Looker Studio. Тщательное тестирование может предотвратить эти ошибки.

Внешние ошибки коннектора обычно можно исправить, проанализировав подробности ошибки (если они доступны) и отладив код для выявления проблемы. Для получения дополнительной информации об отладке коннектора см. раздел «Отладка кода» .

Ошибка Looker Studio

Ошибки Looker Studio — это ошибки, не связанные с кодом коннектора. Например, если пользователь пытается использовать диаграмму временных рядов с источником данных, в котором отсутствует измерение даты/времени.

Если ошибка не связана напрямую с коннектором, то разработчику коннектора ничего не нужно предпринимать. Пользователи могут найти дополнительную помощь, посетив [Центр поддержки Looker Studio].

Отображение сообщений об ошибках

Отображение подробной информации об ошибке в зависимости от статуса администратора.

Когда коннектор выдает ошибку, Looker Studio отображает сообщение об ошибке в зависимости от статуса администратора пользователя.

• Если пользователь является администратором , он увидит все подробности. Это включает в себя сообщение об ошибке, тип ошибки и трассировку стека.
• Если пользователь не является администратором, он увидит подробности только в том случае, если сообщение об ошибке будет понятным для пользователя. Подробнее о том, как показывать сообщения об ошибках пользователям без прав администратора, см. в разделе «Выдача ошибок, видимых пользователям» .

Ключевой момент: Реализуйте функцию isAdminUser() для идентификации администраторов, чтобы пользователям коннектора отображался необходимый уровень детализации.

Выдача ошибок, видимых пользователю.

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

Пример:

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, о том, как включить запись исключений в скрипт и как безопасно идентифицировать пользователей в целях отладки, см. раздел «Использование ведения журналов Stackdriver» .

УСТАРЕЛО: Используйте префикс DS_USER: для корректного отображения сообщений об ошибках.

Внимание: Данная функция устарела и будет удалена в июне 2019 года. Переходите на newUserError() . См. раздел "Выброс ошибок, с которыми сталкиваются пользователи" .

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

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

data-studio/errors.gs

Посмотреть на 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");
  }
}

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