Google Cloud 提供的工具可讓您使用 Google Cloud Monitoring 監控專案的穩定性，並透過 Google Cloud Logging 錯誤記錄檔進行偵錯。如果完成使用者意圖失敗，Google Home Analytics (分析) 管道會將指標記錄失敗，並在專案記錄中發布錯誤記錄檔。
排解錯誤時，共有兩個步驟：
- 透過智慧型住宅指標監控專案狀態。
- 查看錯誤記錄檔中的詳細錯誤說明，即可調查問題。
監控錯誤
您可以使用 Google Cloud Monitoring dashboard 存取專案指標。以下幾個重要圖表特別適合用於監控品質和偵錯：
- 「Success Rate」(成功率) 圖表是您監控專案可靠性時最先開始的圖表。圖表中的下降可能代表部分或所有使用者服務中斷。建議您在每次專案變更或更新專案後，密切監控此圖表以觀察任何異常狀況。
- 「第 95 個百分位數的延遲時間」圖表是智慧型住宅動作對使用者執行效能的重要指標。圖表中如果突然出現波動，可能表示您的系統可能無法跟上要求。建議定期查看此圖表，看看是否有任何非預期的行為。
- 解決整合問題時，「錯誤細目」圖表最為實用。對於成功百分比圖表中醒目顯示的每個錯誤，錯誤細目都會顯示一個錯誤代碼。您可以在下表中查看 Google Home platform 標記的錯誤，以及疑難排解方式。
平台錯誤代碼
以下是專案記錄中可能會顯示的一些常見錯誤代碼，方便您找出 Google Home platform 發現的問題。如需疑難排解資訊，請參閱下表。
| 錯誤代碼 | 說明 |
|---|---|
BACKEND_FAILURE_URL_ERROR |
Google 已從您的服務收到 401 以外的 HTTP 4xx 錯誤代碼。
您可以使用 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 嘗試擷取存取權杖時發生 Google 內部錯誤。 如果您在 GCP Logging 中發現這個錯誤的比率提高，請與我們聯絡以取得更多資訊。 |
GAL_INVALID_ARGUMENT |
Google 嘗試擷取存取權杖時發生 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 |
回應 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 查看智慧型住宅服務記錄檔。
|
RESPONSE_TIMEOUT |
要求已在等候回應時逾時。 傳送回應的時限為傳送要求後的 9 秒。請務必在期限內送出回覆。 |
RESPONSE_UNAVAILABLE |
沒有收到回應，或回應未指出狀態。
回應意圖執行要求的回應應根據 智慧型住宅文件妥善建構，並標明狀態。 |
TRANSIENT_ERROR |
暫時性錯誤會自行解決。 這類錯誤通常會出現在裝置或服務中斷時，也無法開啟連至伺服器的新連線。 |
搜尋記錄
在使用指標監控整合作業後，下一步就是使用 Cloud Logging 排解特定錯誤。錯誤記錄是類似 JSON 的項目，內含一些實用資訊，例如時間、錯誤代碼和來源智慧住宅意圖的詳細資料。
Google Cloud 中有多個系統會隨時將記錄檔傳送至您的專案。您必須撰寫查詢來篩選記錄，然後找出所需記錄。查詢可根據「時間範圍」、「資源」、記錄「嚴重性」或自訂項目。
您可以使用查詢按鈕建立自訂篩選器。
如要指定「Time Range」(時間範圍)，請按一下時間範圍選取按鈕 ，然後選擇其中一個提供的選項。這麼做會篩選記錄，並顯示所選時間範圍內產生的記錄。
如要指定資源，請按一下「Resource」下拉式選單，然後選擇「Google Assistant Action Project」。這樣會在查詢中新增篩選器，顯示源自專案的記錄。
使用「嚴重程度」按鈕，即可按照「緊急」、「資訊」、「偵錯」和其他嚴重性記錄等級進行篩選。
您也可以使用 Logs Explorer 中的「Query」(查詢) 欄位輸入自訂項目。此欄位使用的查詢引擎支援字串比對等基本查詢，以及更多進階查詢類型，包括比較器 (<, >=, !=) 和布林運算子 (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 使用手冊，協助您有效率地測試變更。
學習資源
本文件提供排解智慧型住宅動作錯誤的步驟。您也可以查看我們的程式碼研究室，進一步瞭解如何偵錯：
- 對智慧型住宅雲端程式碼研究室進行偵錯：為智慧型住宅雲端整合偵錯的快速入門指南。
- 對本機住家程式碼研究室進行偵錯：針對智慧型住宅本機整合進行偵錯的快速入門指南。