社区连接器的错误处理和错误消息

为了提供良好的用户体验，您的代码应该能正确处理错误。请向用户显示实用的错误消息，消息中应概述解决相应问题所需采取的纠正措施。

本文档介绍了连接器可能发生的错误、错误消息的工作方式以及如何正确处理连接器错误。

信息提示：要详细了解如何在 JavaScript 中处理异常，请参阅 try...catch 语句。

错误类型

用户在使用您的连接器时可能会遇到的错误类型和错误原因通常分为以下三类：

  1. 连接器内部错误
  2. 连接器外部错误
  3. Looker Studio 错误

连接器内部错误和外部错误应该由连接器开发者处理。这些错误是由开发者编写的代码引起的。

连接器内部错误

连接器内部错误发生在连接器执行期间。例如，如果连接器在执行 getData() 期间无法解析 API 响应，就会发生内部错误。在适用的情况下，应采用便于理解的说明来预见和处理此类错误。

要详细了解如何处理连接器内部错误，请参阅处理连接器错误的最佳做法。

连接器外部错误

连接器外部错误发生在连接器执行之后。例如，当针对三个字段的 getData() 请求仅返回两个字段的数据时，就会发生外部错误。虽然 连接器已完成执行，它未能满足 Looker 的请求 Studio。要防止发生此类错误，请进行全面测试。

通过查看错误详细信息（如果可用）和调试代码确定问题，通常可以修复连接器外部错误。要详细了解如何调试连接器，请参阅调试代码。

Looker Studio 错误

Looker Studio 错误是与连接器代码无关的错误。例如： 如果用户尝试将时间序列图表与 日期/时间维度。

如果错误与连接器没有直接关系，则连接器开发者无需执行任何操作。用户可以前往 Looker Studio 帮助中心。

显示错误消息

根据是否拥有管理员身份显示错误详细信息

当连接器抛出错误时，Looker Studio 会显示错误消息 具体取决于用户的管理员身份。

  • 如果用户是管理员用户，那么他们将看到所有详细信息，其中包括错误消息、错误类型和堆栈轨迹。
  • 如果用户不是管理员用户，则只有在错误包含便于理解的消息时，他们才会看到详细信息。要详细了解如何向非管理员用户显示错误消息，请参阅显示面向用户的错误消息。

显示面向用户的错误消息

默认情况下，只有连接器管理员才能看到错误详细信息。这有助于防止无意中泄露敏感信息，例如堆栈轨迹中的 API 密钥。要向非管理员用户显示错误消息，请使用 newUserError() Looker Studio Apps 脚本服务。

示例：

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() 则用于设置仅向管理员用户显示的文本。

处理连接器错误的最佳做法

在连接器代码执行期间，您应该尝试发现并处理尽可能多的错误。例如，可能导致错误或导致出现异常状态的部分常见操作包括：

  • 网址提取尝试失败（瞬时错误、超时）
  • 请求的时间段内没有任何可用数据
  • 无法解析 API 中的数据或对其进行格式设置
  • 授权令牌已被撤消

处理可恢复的错误

如果连接器执行可能会失败但可恢复，则您应该处理此类情况。例如，如果 API 请求因非严重原因（例如服务器负载减少）而失败，那么在显示错误之前，应对其进行重试。

发现并显示错误

应发现并重新显示不可恢复的错误。重新显示的错误应该有助于用户理解错误发生的原因。如果问题可以解决，则应提供详细的纠正措施。

请参阅显示面向用户的错误消息。

将错误记录到 Stackdriver

使用 Stackdriver 记录错误和其他消息。这有助于理解错误、调试问题和发现未处理的异常。

要详细了解 Stackdriver 错误报告、如何为脚本启用异常日志记录功能以及如何出于调试目的安全地识别用户，请参阅使用 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');
}