為提供良好的使用者體驗,程式碼應正確處理錯誤。向使用者呈現可做為行動依據的錯誤訊息,其中概述解決問題的正確步驟。
本文件說明連接器可能發生的錯誤、錯誤訊息的運作方式,以及正確處理連接器錯誤的方法。
資訊:如要進一步瞭解如何處理 JavaScript 中的例外狀況,請參閱 try...catch 陳述式。
錯誤類型
使用者使用連接器時可能會遇到的錯誤類型和原因,通常分為以下三種類別:
連接器內部和外部錯誤應由連接器開發人員處理。發生這些錯誤是因為開發人員編寫的程式碼。
連接器內部錯誤
連接器執行期間發生連接器內部錯誤。例如,如果連接器無法在 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:
前置字串。這個前置字串可用於為非管理員使用者識別安全訊息,實際錯誤訊息並不包含在實際錯誤訊息中。
以下範例包括將錯誤訊息顯示給非管理員使用者,而系統會向管理員使用者顯示錯誤訊息: