refresh_date: 2023-01-06
Google Cloud 提供相關工具，讓您透過 Google Cloud Monitoring 監控專案的穩定性，並透過 Google Cloud Logging 錯誤記錄檔排解問題。每當系統無法滿足使用者意圖時，Google Home Analytics 管道就會在指標中記錄該失敗事件，並在專案記錄中發布錯誤記錄。
排解錯誤的步驟如下：
- 使用智慧住宅指標監控專案狀態。
- 檢查錯誤記錄中的詳細錯誤說明，以調查問題。
監控錯誤
您可以使用 Google Cloud Monitoring dashboards 存取專案指標。以下是幾張特別有助於監控品質和偵錯的重要圖表：
- 成功率圖表是您監控專案可靠性時，首先會看到的圖表。圖表中的下降趨勢可能表示部分或所有使用者發生服務中斷。建議您在專案每次變更或更新後，密切監控這張圖表，查看是否有任何異常情況。
- 錯誤細目圖表最適合用來排解整合問題。成功率圖表醒目顯示的每個錯誤，都會在錯誤細目中顯示錯誤代碼。下表列出 Google Home platform 標示的錯誤，以及排解方式。
平台錯誤代碼
以下列出您可能會在專案記錄中看到的常見錯誤代碼，有助於找出 Google Home platform 偵測到的問題。請參閱下表瞭解疑難排解資訊。
| 錯誤代碼 | 說明 |
|---|---|
BACKEND_FAILURE_URL_ERROR |
Google 從您的服務收到 HTTP 4xx 錯誤代碼 (401 除外)。 在 GCP Logging 中使用 requestId 檢查智慧住宅服務記錄。
|
BACKEND_FAILURE_URL_TIMEOUT |
Google 嘗試連線至您的服務時發生逾時。
確認服務已上線、接受連線，且未超出容量上限。此外，也請確認目標裝置已開機、連上網路並完成同步。 |
BACKEND_FAILURE_URL_UNREACHABLE |
Google 從您的服務收到 HTTP 5xx 錯誤代碼。
在 GCP Logging 中使用 requestId 檢查智慧住宅服務記錄。
|
DEVICE_NOT_FOUND |
合作夥伴服務端沒有這部裝置。
這通常表示資料同步失敗或發生競爭情況。 |
GAL_BAD_3P_RESPONSE |
由於酬載中的格式或值無效，Google 無法剖析帳戶連結服務的回應。
在 GCP Logging 中使用 requestId，檢查帳戶連結服務中的錯誤記錄。
|
GAL_INTERNAL |
Google 嘗試擷取存取權杖時發生內部錯誤。 如果在 GCP Logging 中看到這項錯誤的發生率提高，請與我們聯絡以瞭解詳情。 |
GAL_INVALID_ARGUMENT |
Google 嘗試擷取存取權杖時發生內部錯誤。 如果在 GCP Logging 中看到這項錯誤的發生率提高，請與我們聯絡以瞭解詳情。 |
GAL_NOT_FOUND |
Google 儲存的使用者存取權權杖和重新整理權杖會失效，且無法再重新整理。使用者必須重新連結帳戶，才能繼續使用您的服務。
如果在 GCP Logging 中看到這項錯誤的發生率提高，請與我們聯絡以瞭解詳情。 |
GAL_PERMISSION_DENIED |
未授權共用權杖時，發生 Google 內部錯誤。 如果在 GCP Logging 中看到這項錯誤的發生率提高，請與我們聯絡以瞭解詳情。 |
GAL_REFRESH_IN_PROGRESS |
使用者的存取權杖已過期，且系統正在嘗試重新整理權杖。 這不是問題，無須採取任何行動。 |
INVALID_AUTH_TOKEN |
Google 已收到您服務傳回的 HTTP 401 錯誤代碼。
存取權杖尚未過期，但服務已使其失效。 在 GCP Logging 中使用 requestId 檢查智慧住宅服務記錄。 |
INVALID_JSON |
無法剖析或解讀 JSON 回應。
檢查 JSON 回應的結構是否有無效語法，例如不相符的括號、遺漏的半形逗號、無效字元。 |
OPEN_AUTH_FAILURE |
使用者存取權杖已過期，且 Google 無法重新整理，或 Google 從您的服務收到 HTTP 401 錯誤代碼。 如果這個程式碼的比率增加，請檢查智慧住宅意圖或重新整理權杖要求相關錯誤的比率是否也增加。 |
PARTNER_RESPONSE_INVALID_ERROR_CODE |
回應指出無法辨識的錯誤代碼。
如果要求回應指出錯誤，請務必使用 支援的錯誤代碼。 |
PARTNER_RESPONSE_INVALID_PAYLOAD |
無法將「Response」payload欄位剖析為 JSON 物件。
檢查要求回應中的酬載欄位是否含有相符的括號，以及是否正確建構為 JSON 欄位。 |
PARTNER_RESPONSE_INVALID_STATUS |
回應未指出狀態，或指出錯誤狀態。
意圖完成要求的回應應指出狀態，並使用 SUCCESS, OFFLINE, ERROR, EXCEPTIONS。如要進一步瞭解如何處理錯誤和例外狀況，請參閱
這篇文章。 |
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
要求中有一或多個意圖，但回應中缺少這些意圖。
確認 執行回應的結構正確無誤，且回應中包含要求中所有意圖的結果。 |
PARTNER_RESPONSE_MISSING_DEVICE |
要求中有一或多部裝置，但回應中缺少這些裝置。
確認 執行回應的結構正確無誤，且回應中包含要求中的所有裝置 ID。 |
PARTNER_RESPONSE_MISSING_PAYLOAD |
回應不含 payload 欄位。
請務必在要求回應中加入酬載欄位。如要進一步瞭解如何正確建構執行回應，請參閱 這篇文章。 |
PARTNER_RESPONSE_NOT_OBJECT |
回應無法剖析為 JSON 物件。
檢查要求回應中的所有欄位，確認是否有非預期的字元、不相符的括號或格式錯誤。系統可能不支援部分萬國碼 (Unicode) 字元。此外，也請確認回覆內容已正確結構化為 JSON 物件。 |
PROTOCOL_ERROR |
無法處理要求。
在 Google Cloud Logging 中使用 requestId，查看智慧住宅服務記錄。
|
RELINK_REQUIRED |
回應指出發生 relinkRequired 錯誤，因此系統會提示使用者重新連結 Google 帳戶和合作夥伴帳戶。詳情請參閱 支援的錯誤代碼。 |
RESPONSE_TIMEOUT |
等待回應時要求逾時。
傳送回應的逾時時間為 9 秒 (從傳送要求時算起)。請務必在這段時間內回覆。 |
RESPONSE_UNAVAILABLE |
未收到任何回應，或回應未指出狀態。
意圖完成要求的回應應根據 智慧型住宅文件建構，並指出狀態。 |
TRANSIENT_ERROR |
暫時性錯誤是指會自行解決的錯誤。
這些錯誤通常會導致裝置或服務連線中斷。此外，如果無法開啟與伺服器的新連線， |
搜尋記錄
熟悉使用指標監控整合後，下一步是使用 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使用指南，說明如何有效測試變更。
學習資源
本文提供步驟，協助排解智慧住宅動作的錯誤。如要進一步瞭解如何偵錯，請參閱我們的程式碼研究室：
- 偵錯智慧型住宅程式碼研究室： 智慧型住宅雲端整合偵錯快速入門指南。
- 偵錯本機住家控制程式碼研究室： 快速入門指南，協助偵錯智慧住宅本機整合。