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 偵測到的問題。請參閱下表瞭解疑難排解資訊。如需完整的錯誤代碼清單，請參閱「錯誤和例外狀況」。
| 錯誤代碼 | 說明 | 合作夥伴可採取行動 |
|---|---|---|
ACTION_NOT_AVAILABLE |
指令不適用於裝置目前狀態 (例如裝置處於關閉狀態時發出「設定溫度」指令)。 在履行中驗證裝置特徵和目前狀態邏輯。 |
是 |
AGENT_ISSUE |
合作夥伴的雲端代理程式發生一般問題。
檢查履行記錄中是否有未處理的例外狀況或當機情形。 |
是 |
AGENT_UNAVAILABLE_ERROR |
Google 無法連線至合作夥伴的履行網址。
確認伺服器已連線、防火牆未封鎖 Google，且網址正確無誤。 |
是 |
APP_LAUNCH_FAILED |
無法在目標裝置上啟動第三方應用程式。
確認 appId，以及目標硬體是否支援該應用程式。 |
是 |
AUTH_EXPIRED |
OAuth 存取權杖已過期，無法重新整理。
檢查重新整理權杖輪替，並確認使用者未撤銷存取權。 |
是 |
BACKEND_FAILURE_URL_TIMEOUT |
Google 嘗試連線至您的服務時發生逾時。
確認服務已上線、接受連線，且未超出容量上限。此外，也請確認目標裝置已開機、連上網路並完成同步。 |
|
BACKEND_FAILURE_URL_UNREACHABLE |
Google 從您的服務收到 HTTP 5xx 錯誤代碼。
在 Google Cloud Logging 中使用 requestId，查看智慧住宅服務記錄。
|
|
CHANNEL_SWITCH_FAILED |
裝置無法切換至要求的媒體頻道。
確認使用者的頻道名稱/號碼和訂閱狀態。 |
是 |
CHARGER_ISSUE |
裝置回報充電系統發生硬體問題。
合作夥伴應調查硬體層級的遙測和電池健康狀態。 |
是 |
CHECK_PARTNER_APP |
使用者必須開啟合作夥伴的應用程式才能解決錯誤。
如果錯誤需要複雜的 UI 互動 (例如韌體更新)，請使用這個代碼。 |
是 |
COMMAND_FAILED |
執行指令時發生一般失敗。
查看履行記錄，找出具體 requestId
，找出根本原因。
|
是 |
COMMAND_INSERT_FAILED |
Google 無法將裝置指令加入佇列或處理指令。
調查資料庫寫入效能或內部指令佇列邏輯。 |
是 |
DEVICE_NOT_FOUND |
要求中的裝置 ID 在合作夥伴端不存在。
請確保使用者新增或刪除裝置時，雲端會觸發 requestSync。
|
是 |
ERROR_STATUS |
回應指出非特定「ERROR」狀態，且沒有代碼。
請務必加入特定 errorCode 字串，提升使用者 TTS 和資訊主頁資料的品質。
|
是 |
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_READ_ONLY_MODE_FOR_3P |
合作夥伴端的整合作業處於唯讀狀態。
檢查使用者帳戶是否已遭停權，或處於「僅供檢視」的維護模式。 |
是 |
EXECUTION_GAL_UNLINKED_BY_3P |
第三方服務主動取消連結帳戶。
調查使用者中斷連線的原因 (例如安全性重設)。 |
是 |
EXECUTION_INVALID_JSON |
Google 無法剖析 JSON 回應負載。
檢查回覆內容是否有語法錯誤、缺少的括號或無效字元。 |
是 |
FAULTY_BATTERY |
裝置硬體回報電池故障或沒電。
透過 TTS 或應用程式指示使用者更換實體電池。 |
是 |
FUNCTION_NOT_SUPPORTED |
裝置不支援要求的模式或功能。
確認 SYNC回應如實反映裝置功能。
|
是 |
HARD_ERROR |
非暫時性失敗，必須手動介入才能解決。
適用於永久性硬體故障或無法復原的帳戶狀態。 |
是 |
INVALID_AUTH_TOKEN |
Google 已收到您服務傳回的 HTTP 401 錯誤代碼。
存取權杖尚未過期，但服務已使其失效。 使用 Google Cloud Logging 中的 requestId，查看智慧住宅服務記錄。 |
|
INVALID_JSON |
回應結構無效 (例如缺少必填欄位)。 根據意圖 JSON 結構定義驗證回覆。 |
是 |
LOCK_FAILURE |
智慧門鎖無法移至要求的狀態。
調查鎖具硬體是否卡住、電力不足或馬達故障。 |
是 |
MALFORMED_JSON |
JSON 結構有誤 (例如未關閉的字串或物件)。 請確認你的履行作業使用標準 JSON 程式庫來序列化回應。 |
是 |
MISSING_STATE |
QUERY 回應未包含要求的裝置狀態。
確保每個 QUERY 回應都包含 SYNC 中定義的所有特徵。
|
是 |
NETWORK_PROFILE_NOT_RECOGNIZED |
裝置無法辨識要求的網路設定檔。
確認設定檔名稱字串與 SYNC 回應中支援的設定檔相符。
|
是 |
NOT_IMPLEMENTED |
合作夥伴尚未實作要求的意圖或特徵。
請只在 SYNC 回應中加入您已完整實作的特徵。
|
是 |
OAUTH_RECONNECT_CALL_TO_ACTION |
觸發通知，要求使用者重新連結帳戶。
當使用者工作階段失效，需要手動重新進行 OAuth 驗證時，請使用這個方法。 |
是 |
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 |
回覆未包含所有要求指令/裝置的結果。
要求 commands 陣列中的每個項目都必須有對應的回應項目。
|
是 |
PARTNER_RESPONSE_MISSING_DEVICE |
Google 要求提供的特定裝置未包含在回覆中。
請確保回應包含請求酬載中提供的每個 ID。
|
是 |
PARTNER_RESPONSE_MISSING_PAYLOAD |
回應中缺少必填的「payload」欄位。
確認頂層 JSON 物件包含 payload 鍵。
|
是 |
PARTNER_RESPONSE_NOT_OBJECT |
無法將整個回覆剖析為 JSON 物件。
檢查 HTTP 回應主體中是否有尾端字元或非 JSON 內容。 |
是 |
PROTOCOL_ERROR |
基礎通訊協定發生錯誤。
調查 HTTP 標頭問題或 SSL/TLS 握手失敗情形。 |
是 |
RELINK_REQUIRED |
使用者必須重新連結帳戶，才能繼續使用整合服務。
請確認伺服器在重新整理權杖永久失效時傳回這個代碼。 |
是 |
REQUEST_ID_NOT_FOUND |
Google 找不到這項要求的內部追蹤 ID。
通常是內部平台錯誤；請監控尖峰時段，並與支援團隊聯絡。 |
是 |
RESOURCE_UNAVAILABLE |
要求的資源 (裝置或特徵) 無法使用。
確認裝置是否「忙碌」或暫時停用。 |
是 |
RESPONSE_TIMEOUT |
完成服務未在 9 秒內回應。
縮短後端延遲時間；檢查是否有 DB 查詢速度緩慢或區域網路延遲的問題。 |
是 |
RESPONSE_UNAVAILABLE |
未收到合作夥伴履行網址的回應。
確認服務正在執行，且端點未當機。 |
是 |
SCENE_CANNOT_BE_APPLIED |
無法啟動要求的場景 (例如缺少裝置)。 檢查合作夥伴雲端上使用者場景的內部健康狀態。 |
是 |
STREAM_UNPLAYABLE |
無法啟動或啟動失敗的攝影機串流。
驗證 WebRTC/HLS 信號，並確認串流網址有效。 |
是 |
TIMEOUT |
處理意圖時發生一般逾時錯誤。
檢查雲端與裝置中樞之間的內部服務逾時記錄。 |
是 |
TRANSIENT_ERROR |
暫時性錯誤是指會自行解決的錯誤。
這些錯誤通常會導致裝置或服務連線中斷。此外，如果無法開啟與伺服器的新連線， |
|
UNABLE_TO_LOCATE_DEVICE |
無法使用定位器特徵 (例如，連線失敗) 尋找裝置。 檢查裝置的本機連線 (Wi-Fi/藍牙)。 |
是 |
UNABLE_TO_RING_DEVICE |
已連線至裝置，但無法觸發鈴聲/警報功能。
確認硬體的警報/喇叭狀態和音量。 |
是 |
UNABLE_TO_SILENCE_DEVICE |
裝置無法停止啟用快訊/鈴聲。
調查雲端與實體裝置之間的通訊失敗問題。 |
是 |
UNEXPECTED_ERROR_CHECK_DEVICE_APP |
發生無法預料的錯誤，使用者應檢查合作夥伴應用程式。
如果錯誤沒有 Google 支援的特定對應項目，請使用這個錯誤碼。 |
是 |
UNKNOWN_ERROR |
發生一般性失敗，未提供其他詳細資料。
請盡量以更具體的錯誤代碼取代這個代碼，以利排解問題。 |
是 |
UNLOCK_FAILURE |
智慧門鎖無法進入「已解鎖」狀態。
調查硬體卡住、電池電量不足或 PIN 碼輸入無效等問題。 |
是 |
搜尋記錄
熟悉使用指標監控整合後，下一步是使用 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使用指南，說明如何有效測試變更。
學習資源
本文提供步驟，協助排解智慧住宅動作的錯誤。如要進一步瞭解如何偵錯，請參閱我們的程式碼研究室：
- 偵錯智慧型住宅程式碼研究室： 快速入門指南，協助偵錯智慧型住宅雲端整合功能。
- 偵錯本機住家控制程式碼研究室： 智慧住宅本機整合偵錯快速入門指南。