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