refresh_date: 2023-01-06
Google Cloud 提供工具，可透過 Google Cloud Monitoring 監控專案的可靠性，並透過 Google Cloud Logging 錯誤記錄偵錯問題。當執行使用者意圖時發生失敗時，Google Home Analytics 管道會在指標上記錄該失敗，並在專案記錄中發布錯誤記錄。
您可以採取兩個步驟來排解錯誤：
- 使用智慧住宅指標監控專案狀態。
- 檢查錯誤記錄中的詳細錯誤說明，以便調查問題。
監控錯誤
您可以使用 Google Cloud Monitoring dashboard 存取專案指標。以下是一些用於監控品質和偵錯的重要圖表：
- 監控專案的可靠度時，成功率圖表是第一個要開始查看的圖表。這張圖表的資料量減少，可能表示部分或所有使用者都無法存取服務。建議您在每次變更或更新專案後，密切監控這張圖表，看看是否有任何異常現象。
- 如要排解整合問題，錯誤細目圖表最有用。成功率圖表中醒目顯示的每個錯誤，都會在錯誤細目中顯示錯誤代碼。您可以在下表中查看 Google Home platform 標示的錯誤，以及如何排解這些錯誤。
平台錯誤代碼
以下是您可能會在專案記錄中看到的部分常見錯誤代碼，可用來找出 Google Home platform 偵測到的問題。如需疑難排解資訊，請參閱下表。
| 錯誤代碼 | 說明 |
|---|---|
BACKEND_FAILURE_URL_ERROR |
Google 從你的服務收到 401 以外的 HTTP 4xx 錯誤代碼。 請使用 GCP 記錄中的 requestId 查看智慧型家居服務記錄。 |
BACKEND_FAILURE_URL_TIMEOUT |
Google 在嘗試連線至您的服務時，要求逾時。
請確認您的服務已上線、接受連線，且未超出容量。此外，請確認目標裝置已開機、上線及同步。 |
BACKEND_FAILURE_URL_UNREACHABLE |
Google 收到您服務傳送的 HTTP 5xx 錯誤代碼。
請使用 GCP 記錄中的 requestId 查看智慧型家居服務記錄。 |
DEVICE_NOT_FOUND |
合作夥伴服務端沒有這部裝置。
This 通常表示資料同步處理失敗或發生競爭條件。 |
GAL_BAD_3P_RESPONSE |
由於酬載中格式或值無效，Google 無法剖析帳戶連結服務的回應。 請使用 GCP 記錄中的 requestId，查看帳戶連結服務中的錯誤記錄。 |
GAL_INTERNAL |
Google 嘗試擷取存取權權杖時發生 Google 內部錯誤。 如果您發現 GCP 記錄中發生此錯誤的頻率增加，請與我們聯絡以取得更多資訊。 |
GAL_INVALID_ARGUMENT |
Google 嘗試擷取存取權權杖時發生 Google 內部錯誤。 如果您發現 GCP 記錄中發生此錯誤的頻率增加，請與我們聯絡以取得更多資訊。 |
GAL_NOT_FOUND |
儲存在 Google 中的使用者存取權杖和更新權杖會失效，且無法再進行重新整理。使用者必須重新連結帳戶，才能繼續使用您的服務。 如果您發現 GCP 記錄中發生此錯誤的頻率增加，請與我們聯絡以取得更多資訊。 |
GAL_PERMISSION_DENIED |
權杖共用功能未經授權時，發生 Google 內部錯誤。 如果您發現 GCP 記錄中發生此錯誤的頻率增加，請與我們聯絡以取得更多資訊。 |
GAL_REFRESH_IN_PROGRESS |
使用者的存取權杖已過期，且另一個同時嘗試重新整理的動作已在進行中。 這並非問題，您無須採取任何行動。 |
INVALID_AUTH_TOKEN |
Google 已從您的服務收到 HTTP 401 錯誤代碼。
存取權杖並未過期，但您的服務已將其設為無效。使用 GCP 記錄中的 requestId 查看智慧型家居服務記錄。 |
INVALID_JSON |
無法剖析或解讀 JSON 回應。
檢查 JSON 回應的結構是否有無效的語法，例如不相符的括號、缺少的逗號、無效的字元。 |
OPEN_AUTH_FAILURE |
使用者的存取權憑證已過期，Google 無法重新整理，或是 Google 已從您的服務收到 HTTP 401 錯誤代碼。 如果這個代碼的發生率增加，請檢查是否也出現與智慧型家居意圖或重新整理權杖要求相關的錯誤。 |
PARTNER_RESPONSE_INVALID_ERROR_CODE |
回應指出無法辨識的錯誤代碼。
如果要求回應指出錯誤，請務必使用 支援的錯誤代碼中提供的錯誤代碼。 |
PARTNER_RESPONSE_INVALID_PAYLOAD |
回應 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 物件。
檢查要求回應中的所有欄位，看看是否有非預期的字元、不相符的括號或格式錯誤。系統可能不支援部分萬國碼字元。此外，請確認回應的 JSON 物件結構正確無誤。 |
PROTOCOL_ERROR |
無法處理要求。
Google Cloud Logging 中的 requestId 可用來查看智慧型家居服務記錄。 |
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，並引導您有效測試變更。
學習資源
本文提供智慧型家居動作的錯誤排解步驟。您也可以參閱我們的程式碼研究室，進一步瞭解偵錯作業：
- 智慧型住宅程式碼研究室偵錯：快速入門指南，可用於偵錯智慧型住宅雲端整合功能。
- 偵錯本地居家程式碼研究室：快速入門指南，可用於偵錯智慧型居家本地整合功能。