Чтобы обеспечить хорошее взаимодействие с пользователем, ваш код должен правильно обрабатывать ошибки. Предоставляйте пользователям действенные сообщения об ошибках, в которых описываются действия по устранению проблемы.
В этом документе описываются ошибки, которые могут произойти с соединителями, как работают сообщения об ошибках и как правильно обрабатывать ошибки соединителей.
Информация: Чтобы узнать больше об обработке исключений в JavaScript, см. оператор try...catch .
Типы ошибок
Типы и причины ошибок, с которыми может столкнуться пользователь при использовании коннектора, обычно попадают в одну из следующих трех категорий:
Внутренние и внешние ошибки соединителя должны устраняться разработчиком соединителя. Эти ошибки возникают из-за кода, написанного разработчиком.
Внутренняя ошибка соединителя
Во время выполнения соединителя возникают внутренние ошибки соединителя. Например, если соединитель не может проанализировать ответ API во время выполнения getData() . Эти ошибки следует предвидеть и устранять с помощью понятных для пользователя объяснений, где это применимо.
Дополнительные сведения об обработке внутренних ошибок соединителя см. в разделе Рекомендации по обработке ошибок соединителя .
Внешняя ошибка разъема
Внешние ошибки соединителя возникают после выполнения соединителя. Например, когда запрос getData() для трех полей возвращает данные только для двух. Хотя коннектор завершил выполнение, он не удовлетворил запрос Looker Studio. Тщательное тестирование может предотвратить эти ошибки.
Внешние ошибки соединителя обычно можно исправить, просмотрев сведения об ошибке (если они доступны) и отладив код для выявления проблемы. Дополнительные сведения об отладке соединителя см. в разделе Отладка кода .
Ошибка Looker Studio
Ошибки Looker Studio — это ошибки, не связанные с кодом вашего коннектора. Например, если пользователь пытается использовать диаграмму временных рядов с источником данных без измерения даты и времени.
Если ошибка не связана напрямую с соединителем, разработчик соединителя не должен предпринимать никаких действий. Пользователи могут получить дополнительную помощь, посетив Справочный центр Looker Studio .
Показ сообщений об ошибках
Отображение сведений об ошибке на основе статуса администратора
Когда соединитель выдает ошибку, Looker Studio отображает сообщение об ошибке в зависимости от статуса администратора пользователя.
- Если пользователь является администратором, он увидит все подробности. Сюда входит сообщение об ошибке, тип ошибки и трассировка стека.
- Если пользователь не является администратором, он увидит подробности только в том случае, если ошибка содержит понятное для пользователя сообщение. Дополнительные сведения о показе сообщений об ошибках пользователям, не являющимся администраторами, см. в разделе «Выдача сообщений об ошибках пользователю» .
Выбрасывание ошибок, с которыми сталкивается пользователь
По умолчанию сведения об ошибках видят только администраторы соединителя. Это помогает предотвратить непреднамеренное раскрытие конфиденциальной информации, например ключа API в трассировке стека. Чтобы показывать сообщения об ошибках пользователям, не являющимся администраторами, используйте newUserError() из службы сценариев приложений 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: для безопасных сообщений об ошибках.
Чтобы предоставить понятные сообщения об ошибках пользователям, не являющимся администраторами, включите префикс DS_USER: в сообщения об ошибках. Этот префикс используется для идентификации безопасных сообщений для пользователей, не являющихся администраторами, и не включается в фактическое сообщение об ошибке.
Следующие примеры включают случай, когда сообщение об ошибке будет показано пользователям, не являющимся администраторами, и другой, когда сообщение об ошибке будет показано только пользователям с правами администратора: