Google Cloud 提供相關工具，讓您透過 Google Cloud Monitoring 監控專案的可靠性，並透過 Google Cloud Logging 錯誤記錄偵錯問題。每當系統無法滿足使用者意圖時，Google Home Analytics 管道會在指標中記錄該失敗事件，並在專案記錄中發布錯誤記錄。
排解錯誤的步驟如下：
- 使用智慧住宅指標監控專案狀態。
- 查看錯誤記錄中的詳細錯誤說明，調查問題。
您可以選擇與其他使用者共用，測試動作。請務必妥善處理錯誤和例外狀況。
監控錯誤
您可以使用 Google Cloud Monitoring dashboards 存取專案指標。以下是幾張特別有助於監控品質和偵錯的重要圖表：
- 成功率圖表是監控專案可靠性時，首先要查看的圖表。圖表中的下降趨勢可能表示部分或所有使用者發生服務中斷。建議您在專案每次變更或更新後，密切監控這張圖表，查看是否有任何異常情況。
- 第 95 個百分位數延遲圖表是重要指標，可顯示Cloud-to-cloud整合服務為使用者提供的效能。如果這張圖表出現劇烈波動，可能表示系統無法及時處理要求。建議您定期查看這張圖表，瞭解是否有任何非預期的行為。
- 「錯誤細目」圖表最適合用來排解整合問題。成功率圖表中醒目顯示的每個錯誤，都會在錯誤細目中顯示錯誤代碼。下表列出 Google Home platform 標記的錯誤，以及疑難排解方式。
常見的平台錯誤代碼
以下列出您可能會在專案記錄中看到的常見錯誤代碼，有助於找出 Google Home platform 偵測到的問題。請參閱下表瞭解疑難排解資訊。如需完整的錯誤代碼清單，請參閱「錯誤和例外狀況」。
| 錯誤代碼 | 說明 | 合作夥伴可採取行動 |
|---|---|---|
AGENT_ISSUE |
合作夥伴的雲端代理程式發生一般問題。
檢查執行要求記錄中是否有未處理的例外狀況或當機情形。 |
是 |
AGENT_UNAVAILABLE_ERROR |
Google 無法連線至合作夥伴的履行網址。 確認伺服器已連線、防火牆未封鎖 Google，且網址正確無誤。 |
是 |
BACKEND_FAILURE_URL_TIMEOUT |
Google 嘗試連線至您的服務時發生逾時。
確認服務已上線、接受連線，且未超出容量上限。此外，也請確認目標裝置已開機、連上網路並完成同步。 |
|
BACKEND_FAILURE_URL_UNREACHABLE |
Google 從您的服務收到 HTTP 5xx 錯誤代碼。
在 Google Cloud Logging 中使用 requestId，查看智慧住宅服務記錄。調查伺服器當機、逾時或 502/503 閘道錯誤。
|
|
COMMAND_FAILED |
執行指令時發生一般失敗。 查看執行要求記錄，找出具體 requestId
，找出根本原因。
|
是 |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google 從你的履行服務收到 HTTP 4xx 錯誤 (401 除外)。 查看網路伺服器記錄，瞭解是否有 403、404 或 400 回應。 |
是 |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
robots.txt 或安全性篩選器封鎖了完成網址。 確認 Google 檢索器/服務可存取你的執行要求端點。 |
是 |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE |
Google 從你的履行服務收到 HTTP 5xx 錯誤。 確認端點網址服務穩定、正確且可公開連線，且服務正在執行。新增健康狀態檢查和重試處理。 調查伺服器當機、逾時或 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 秒內回應。 縮短後端延遲時間；檢查是否有 DB 查詢速度緩慢或區域網路延遲的問題。 |
是 |
RESPONSE_UNAVAILABLE |
未收到合作夥伴履行網址的回應。 確認服務正在執行，且端點未當機。 |
是 |
TIMEOUT |
處理意圖時發生一般逾時錯誤。
檢查雲端與裝置中樞之間的內部服務逾時記錄。 |
是 |
搜尋記錄
熟悉使用指標監控整合後，下一步是使用 Cloud Logging 排解特定錯誤。錯誤記錄是類似 JSON 的項目，包含時間、錯誤代碼等實用資訊，以及原始智慧住宅意圖的詳細資料。
Google Cloud 內有多個系統會持續將記錄傳送至您的專案。您需要編寫查詢來篩選記錄，找出所需項目。查詢可依時間範圍、資源、記錄嚴重程度或自訂項目進行。
您可以使用查詢按鈕建立自訂篩選器。
如要指定時間範圍，請按一下時間範圍選取按鈕 ，然後選擇其中一個選項。系統會篩選記錄，並顯示所選時間範圍內的記錄。
如要指定資源，請按一下「資源」下拉式選單，然後選擇「Google 助理動作專案」。這會在查詢中新增篩選器，顯示來自專案的記錄。
使用「嚴重性」按鈕，依「緊急」、「資訊」、「偵錯」和其他嚴重性記錄層級進行篩選。
您也可以使用 Logs Explorer 中的「查詢」欄位輸入自訂項目。這個欄位使用的查詢引擎支援字串比對等基本查詢，以及比較子 (<, >=, !=) 和布林運算子 (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使用指南，說明如何有效測試變更。
學習資源
本文提供步驟，協助排解智慧住宅動作的錯誤。如要進一步瞭解如何偵錯，請參閱我們的程式碼研究室：
- 偵錯智慧型住宅程式碼研究室： 快速入門指南，協助偵錯智慧型住宅雲端整合功能。
- 偵錯本機住家 Codelab： 快速入門指南，協助偵錯智慧型住宅本機整合功能。