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

為提供良好的使用者體驗,程式碼應正確處理錯誤。向使用者呈現可做為行動依據的錯誤訊息,其中概述解決問題的正確步驟。

本文件說明連接器可能發生的錯誤、錯誤訊息的運作方式,以及正確處理連接器錯誤的方法。

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

錯誤類型

使用者使用連接器時可能會遇到的錯誤類型和原因,通常分為以下三種類別:

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

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

連接器內部錯誤

連接器執行期間發生連接器內部錯誤。例如,如果連接器無法在 getData() 執行期間剖析 API 回應,在適當情況下,您應預期及處理這些錯誤,並提供使用者容易理解的說明。

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

連接器外部錯誤

連接器執行後發生外部錯誤。例如,當三個欄位的 getData() 要求只會傳回兩個欄位的資料時。雖然連接器已完成執行作業,但不符合來自 Looker Studio 的要求。全面測試有助於避免這類錯誤。

連接器外部錯誤通常可以藉由查看錯誤詳細資料 (如有) 並對程式碼進行偵錯來找出問題,藉此修正。如要進一步瞭解如何對連接器進行偵錯,請參閱「對程式碼進行偵錯」。

Looker Studio 錯誤

Looker Studio 錯誤是與連接器程式碼無關的錯誤。舉例來說,如果使用者嘗試使用時間序列圖,但沒有日期/時間維度。

如果錯誤與連接器沒有直接關聯,連接器開發人員便無須採取任何行動。如需進一步協助,使用者可以造訪 Looker Studio 說明中心

顯示錯誤訊息

根據管理員狀態顯示錯誤詳細資料

連接器擲回錯誤時,Looker Studio 會根據使用者的管理員狀態顯示錯誤訊息。

  • 如果使用者是管理員使用者,則可查看所有詳細資料。包括錯誤訊息、錯誤類型和堆疊追蹤。
  • 如果使用者「不是」管理員使用者,則只有在錯誤包含使用者容易理解的訊息時,他們才會看到詳細資料。如要進一步瞭解如何向非管理員使用者顯示錯誤訊息,請參閱擲回使用者端的錯誤

擲回使用者遇到的錯誤

根據預設,只有連接器管理員才能查看錯誤詳細資料。這有助於防止不慎揭露機密資訊,例如堆疊追蹤中的 API 金鑰。如要向非管理員使用者顯示錯誤訊息,請使用 Looker Studio Apps Script 服務中的 newUserError()

示例:

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');
}