refresh_date: 2023-01-06
Google Cloud 提供多項工具，可讓您透過 Google Cloud Monitoring 監控專案的可靠性，並使用 Google Cloud Logging 錯誤記錄偵錯。每當執行使用者意圖失敗時，Google Home Analytics 管道會將失敗記錄在指標中，並在專案記錄中發布錯誤記錄。
排解錯誤的步驟有兩個：
- 使用智慧住宅指標監控專案狀態。
- 查看錯誤記錄中的詳細錯誤說明，調查問題。
監控錯誤
您可以使用 Google Cloud Monitoring dashboard 存取專案指標。以下幾張重要圖表特別適合用來監控品質和偵錯：
- 監控專案的可靠性時，請先查看「Success Rate」(成功率) 圖表。如果圖表中的數據下降，可能代表部分或所有使用者遇到服務中斷。建議您在每次變更或更新專案後，密切監控這張圖表，看看是否有任何異常。
- 「Error Breakdown」(錯誤細目) 圖表最適合用於疑難排解整合問題。成功率圖表中醒目顯示的每個錯誤，都會在錯誤細目中顯示錯誤代碼。下表列出 Google Home platform 標記的錯誤，以及疑難排解方式。
常見平台錯誤代碼
以下列出專案記錄中可能出現的一些常見錯誤代碼，方便您找出 Google Home platform 偵測到的問題。請參閱下表，瞭解疑難排解資訊。如需錯誤代碼的完整清單，請參閱「錯誤和例外狀況」。
| 錯誤代碼 | 說明 | 合作夥伴可採取的行動 |
|---|---|---|
AGENT_ISSUE |
合作夥伴的雲端代理發生一般問題。
請檢查執行記錄中是否有未處理的例外狀況或當機情形。 |
是 |
AGENT_UNAVAILABLE_ERROR |
Google 無法連上合作夥伴的出貨網址。
請確認伺服器已連上網路、防火牆未封鎖 Google，且網址正確無誤。 |
是 |
COMMAND_FAILED |
執行指令時發生一般失敗。 請查看執行記錄，找出特定 requestId 的根本原因。
|
是 |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google 從您的執行要求收到 HTTP 4xx 錯誤 (401 除外)。 查看網路伺服器記錄，瞭解是否有 403、404 或 400 回應。 |
是 |
EXECUTION_BACKEND_FAILURE_URL_TIMEOUT |
Google 嘗試連線至您的服務時逾時。
請確認服務已上線、接受連線，且未超過容量。此外，請確認目標裝置已開機、連上網路並完成同步。 |
是 |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
出貨網址遭到 robots.txt 或安全性篩選器封鎖。
請確認 Google 的檢索器/服務可以存取您的執行端點。 |
是 |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE |
Google 從你的執行服務收到 HTTP 5xx 錯誤。
請確認端點網址服務穩定、正確、可公開存取，且服務正在運作。使用 Google Cloud Logging 中的 requestId 檢查智慧住宅服務記錄。新增健康狀態檢查和重試處理機制。
調查伺服器當機、逾時或 502/503 閘道錯誤。
|
是 |
EXECUTION_BAILOUT_INVALID_RESPONSE |
JSON 回應格式錯誤，因此處理作業已中止。
使用 JSON 驗證工具，確保回覆嚴格遵循意圖結構定義。 |
是 |
EXECUTION_GAL_BAD_3P_RESPONSE |
權杖回應格式無效，因此無法連結帳戶。
確認 OAuth 伺服器的回應格式符合 Google 的規定。 |
是 |
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES |
使用者的帳戶缺少執行這項操作所需的權限。
檢查 OAuth 期間要求的範圍，並確認這些範圍符合必要特徵。 |
是 |
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P |
合作夥伴雲端指出使用者已取消連結帳戶。
請確認 agentUserId 對應關係穩定且未遭清除。
|
是 |
EXECUTION_GAL_NOT_FOUND |
儲存在 Google 的使用者存取權杖和更新權杖無效或無法更新，因此無法驗證及存取合作夥伴服務。
確保權杖保持有效且同步，妥善處理帳戶狀態變更，並在確認權杖已撤銷時，要求使用者重新連結帳戶。 |
|
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P |
在合作夥伴端，整合作業處於唯讀狀態。
檢查使用者帳戶是否遭到停權，或處於「僅供檢視」維護模式。 |
是 |
EXECUTION_GAL_UNLINKED_BY_3P |
第三方服務主動取消連結帳戶。
調查使用者連線中斷的原因 (例如安全性重設)。確認合作夥伴的 OAuth 伺服器正確回應 Google 的 refresh_token 要求，順利核發新的存取權杖。 |
是 |
EXECUTION_INVALID_JSON |
Google 無法剖析 JSON 回應酬載。
請檢查回覆中是否有語法錯誤、缺少括號或無效字元。 |
是 |
INVALID_AUTH_TOKEN |
Google 從您的服務收到 HTTP 401 錯誤代碼。
存取權杖尚未過期，但服務已將其撤銷。 使用 Google Cloud Logging 中的 requestId 查看智慧住宅服務記錄。 |
|
INVALID_JSON |
回應結構無效 (例如缺少必要欄位)。
根據意圖 JSON 結構定義驗證回應。 |
是 |
MALFORMED_JSON |
JSON 結構損毀 (例如未封閉的字串或物件)。 請確認執行要求使用標準 JSON 程式庫，將回應序列化。 |
是 |
NOT_IMPLEMENTED |
合作夥伴尚未導入要求的意圖或特徵。
請只在 SYNC 回應中加入已完整實作的特徵。
|
是 |
OPEN_AUTH_FAILURE |
使用者的存取權杖已過期，且 Google 無法重新整理，或 Google 收到服務傳回的 HTTP 401 錯誤代碼。 如果這個代碼的發生率增加，請檢查與智慧住宅意圖或更新權杖要求相關的錯誤發生率是否也增加。 |
|
PARTNER_RESPONSE_INVALID_ERROR_CODE |
傳回的 errorCode 字串不在 Google 支援的清單中。將內部錯誤對應至官方錯誤清單。 |
是 |
PARTNER_RESPONSE_INVALID_PAYLOAD |
回應中的 payload 欄位不是有效的 JSON 物件。請驗證執行要求回應的根結構。 |
是 |
PARTNER_RESPONSE_INVALID_STATUS |
回應 status 不是 SUCCESS、ERROR 或 OFFLINE。
請確認回應中的每項裝置結果都包含有效的狀態字串。 |
是 |
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
回覆未包含所有要求指令/裝置的結果。 請根據 Google Home 開發人員說明文件，驗證回應結構。確認回應未因內部伺服器錯誤而遭到截斷或傳回空白主體。要求 commands 陣列中的每個項目都必須有對應的回應項目。 |
是 |
PARTNER_RESPONSE_MISSING_DEVICE |
Google 要求的特定裝置已從回覆中省略。
請確保回應包含要求酬載中提供的每個 ID。
|
是 |
PARTNER_RESPONSE_MISSING_PAYLOAD |
回應缺少必要的 payload 欄位。
確認頂層 JSON 物件包含 payload 鍵。
|
是 |
PARTNER_RESPONSE_NOT_OBJECT |
無法將整個回應剖析為 JSON 物件。
請檢查 HTTP 回應主體中是否有結尾字元或非 JSON 內容。請確認 payload.commands[] 是適當的 JSON 物件，包含 ID、狀態和選用狀態。 |
是 |
REQUEST_ID_NOT_FOUND |
Google 找不到要求的內部追蹤 ID。
通常是內部平台錯誤；請監控是否有錯誤率飆升的情況，並與支援團隊聯絡。 |
是 |
RESOURCE_UNAVAILABLE |
要求的資源 (裝置或特徵) 無法使用。
請檢查裝置是否「忙碌中」或暫時停用。 |
是 |
RESPONSE_TIMEOUT |
執行服務未在 9 秒內回應。
縮短後端延遲時間；檢查資料庫查詢速度是否緩慢，或區域網路是否延遲。 |
是 |
RESPONSE_UNAVAILABLE |
未收到合作夥伴執行要求網址的回應。
請確認服務正在運作，且端點未當機。 |
是 |
TIMEOUT |
處理意圖時發生一般逾時錯誤。
查看記錄，瞭解雲端和裝置中樞之間的內部服務是否逾時。 |
是 |
搜尋記錄
熟悉如何使用指標監控整合後，下一步是使用 Cloud Logging 排解特定錯誤。錯誤記錄是類似 JSON 的項目，欄位包含實用資訊，例如時間、錯誤代碼，以及原始智慧住宅意圖的詳細資料。
Google Cloud 內有多個系統會隨時將記錄傳送至您的專案。您需要編寫查詢來篩選記錄，找出所需項目。查詢可以依據「日期範圍」、「資源」、記錄「嚴重性」 或自訂項目。
您可以使用查詢按鈕建立自訂篩選器。
如要指定「日期範圍」，請按一下日期範圍選取按鈕 ，然後選擇其中一個提供的選項。系統會篩選記錄，並顯示在所選日期範圍內產生的記錄。
如要指定「Resource」(資源)，請按一下「Resource」(資源) 下拉式選單，然後選擇「Google Assistant Action Project」(Google 助理動作專案)。這會在查詢中新增篩選器，顯示來自專案的記錄。
使用「Severity」(嚴重性) 按鈕，依「Emergency」(緊急)、「Info」(資訊)、「Debug」(偵錯) 和其他嚴重性記錄層級篩選。
您也可以使用 Logs Explorer 中的「Query」(查詢) 欄位輸入自訂項目。這個欄位使用的查詢引擎支援字串比對等基本查詢，以及比較子 (<, >=, !=) 和布林運算子 (AND, OR, NOT) 等更進階的查詢類型。
舉例來說，下列自訂項目會傳回源自 LIGHT 裝置類型的錯誤：
resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"
請前往查詢庫，查看更多有效查詢記錄的範例。
測試修正
找出錯誤並套用更新修正後，建議您使用 Google Home Test Suite 徹底測試修正。我們提供 Test Suite 使用手冊，逐步引導您有效測試變更。
學習資源
本文說明如何排解智慧住宅動作中的錯誤。您也可以查看程式碼實驗室，進一步瞭解偵錯：
- 偵錯智慧住宅程式碼實驗室：快速入門指南，說明如何偵錯智慧住宅雲端整合。
- 偵錯本機住宅程式碼研究室：快速入門指南，說明如何偵錯智慧住宅本機整合。