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 Logging 中使用 requestId，即可查看智慧型住宅服務記錄。
|
DEVICE_NOT_FOUND |
裝置不存在於合作夥伴服務端。
通常這通常表示資料同步處理或競爭狀況失敗。 |
GAL_BAD_3P_RESPONSE |
由於酬載中格式或值無效，Google 無法剖析帳戶連結服務的回應。 請使用 GCP 記錄中的 requestId，查看帳戶連結服務中的錯誤記錄。 |
GAL_INTERNAL |
Google 嘗試擷取存取權杖時發生 Google 內部錯誤。 如果您發現 GCP 記錄中發生此錯誤的頻率增加，請與我們聯絡以取得更多資訊。 |
GAL_INVALID_ARGUMENT |
Google 嘗試擷取存取權權杖時發生 Google 內部錯誤。 如果您發現 GCP 記錄中發生此錯誤的頻率增加，請與我們聯絡以取得更多資訊。 |
GAL_NOT_FOUND |
使用者儲存在 Google 中的存取權杖和更新權杖會失效，也無法再重新整理。使用者必須重新連結帳戶，才能繼續使用您的服務。 如果您在 GCP Logging 中發現這個錯誤的頻率提高，請與我們聯絡以瞭解詳情。 |
GAL_PERMISSION_DENIED |
權杖共用功能未經授權時，發生 Google 內部錯誤。 如果您發現 GCP 記錄中發生此錯誤的頻率增加，請與我們聯絡以取得更多資訊。 |
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 |
無法將回應 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 中有多個系統會隨時將記錄傳送至您的專案。您需要編寫查詢來篩選記錄，並找出所需的記錄。查詢可以根據時間範圍、資源、記錄嚴重性或自訂項目。
你可以使用查詢按鈕建立自訂篩選器。
如要指定「Time Range」(時間範圍)，請按一下時間範圍選取按鈕 ，然後選擇其中一個提供的選項。這會篩選記錄，並顯示來自所選時間範圍內的記錄。
如要指定資源，請按一下「資源」下拉式選單，然後選擇「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，並引導您有效測試變更。
學習資源
本文提供智慧型家居動作錯誤的疑難排解步驟。您也可以參閱我們的程式碼研究室，進一步瞭解偵錯作業：
- 智慧型住宅程式碼研究室偵錯：快速入門指南，可用於智慧型住宅雲端整合偵錯。
- 偵錯本地智慧家庭程式碼研究室：快速入門指南，協助您偵錯智慧型家居本地整合功能。