社群連接器的錯誤處理和訊息

為提供良好的使用者體驗，您的程式碼必須正確處理錯誤。 向使用者提供可採取行動的錯誤訊息，概述應用程式的修正步驟 進而解決問題

本文說明連接器可能發生的錯誤及錯誤狀況 訊息的運作方式，以及如何正確處理連接器錯誤。

資訊：如要進一步瞭解如何處理 JavaScript 中的例外狀況，請參閱 try...catch 陳述式。

錯誤類型

使用者運用您的工具時，可能遇到的錯誤類型和 連接器通常屬於以下三類：

  1. 連接器內部錯誤
  2. 連接器外部錯誤
  3. Looker Studio 錯誤

連接器內部和外部錯誤應由連接器處理 開發人員。這些錯誤是因開發人員編寫的程式碼所致。

連接器內部錯誤

連接器執行期間發生連接器內部錯誤。舉例來說 連接器在執行 getData() 期間無法剖析 API 回應。 這些錯誤應該可以預期，也能以使用者容易理解的說明進行處理 視情況而定。

如要進一步瞭解如何處理連接器內部錯誤，請參閱 處理連接器錯誤的最佳做法。

連接器外部錯誤

連接器執行後發生外部錯誤。舉例來說 三個欄位的 getData() 要求只會傳回兩個欄位的資料。雖然 連接器已完成執行作業，但不符合 Looker 的要求 嚴謹測試可避免這些錯誤。

連接器外部錯誤通常可透過檢查錯誤詳細資料加以修正 (如果 ) 並偵錯程式碼，以找出問題。如要進一步瞭解 對連接器進行偵錯，請參閱「對程式碼進行偵錯」。

Looker Studio 錯誤

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() 則會設定只對管理員使用者顯示的文字。

處理連接器錯誤的最佳做法

請盡可能在維護期間 連接器程式碼的執行。例如，一些需要執行 造成錯誤或不當狀態的情況包括：

  • 網址擷取失敗 (暫時性錯誤、逾時)
  • 要求的時間範圍內沒有資料
  • 無法剖析 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');
}