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

為提供良好的使用者體驗，程式碼應正確處理錯誤。 向使用者顯示提供可行建議的錯誤訊息，說明解決問題的修正步驟。

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

資訊：如要進一步瞭解如何在 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');
}